Developer API — COVEN AI

Overview

REST API

Standard HTTP endpoints with Bearer token auth. JSON responses. Works with any language or framework.

MCP Server

Native Model Context Protocol support. Add COVEN as a tool to any Claude, GPT, or MCP-compatible agent in minutes.

OpenAPI Spec

Machine-readable spec at /openapi.json. Auto-generate SDKs, import into Postman, or let agents discover automatically.

Base URL https://api.covenai.io

Authentication

All authenticated endpoints require a Bearer token in the Authorization header. Get your API key from Mission Control.

curl -H "Authorization: Bearer caa_your_key_here" \
  "https://api.covenai.io/api/v1/sites"

Public endpoints — no auth: POST https://aa.covenai.io/api/public/scan, GET /api/v1/status, and GET /mcp (discovery). All other /api/v1/* endpoints require a valid API key.

Get your API key → Open Mission Control. API access is included with paid tiers when they activate after the public beta; during beta, key issuance is invitation-only — join the waitlist.

Public Endpoints

These endpoints require no authentication. Use them to scan a single URL, check API health, or discover the MCP server.

POST https://aa.covenai.io/api/public/scan No Auth

Scan any URL across the five scored agent-readability dimensions — Structure, Citability, Discoverability, Agent Interface, and Transactability. Returns dimension scores, issues, passes, and a researchSignals array containing Agent Correlation (research signal at 0% weight, kept separate from the scored composite). Methodology version 2.0.1.

Body Parameters

Name	Type	Required	Description
url	string	Required	The URL to scan (e.g. `https://example.com`)

Request

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' \
  "https://aa.covenai.io/api/public/scan"

Response

{
  "url": "https://example.com",
  "domain": "example.com",
  "scannedAt": "2026-04-28T08:00:00.000Z",
  "methodologyVersion": "2.0.1",
  "overallScore": 74,
  "grade": "B",
  "dimensions": [
    { "id": "structure",        "weight": 0.25, "score": 82 },
    { "id": "citability",       "weight": 0.25, "score": 71 },
    { "id": "discoverability",  "weight": 0.15, "score": 68 },
    { "id": "agent_interface",  "weight": 0.20, "score": 75 },
    { "id": "transactability",  "weight": 0.15, "score": 70 }
  ],
  "researchSignals": [
    { "id": "agent_correlation", "weight": 0, "score": 62 }
  ]
}

GET /api/v1/status No Auth

Health check endpoint. Returns current API operational status, version, and a link back to these docs.

Response

{
  "status": "operational",
  "version": "1.0.0",
  "docs": "https://covenai.io/developers"
}

GET /mcp No Auth

Model Context Protocol server discovery. Returns metadata describing the MCP server name, version, endpoint, and protocol. POST to the same path with a JSON-RPC 2.0 envelope to call tools (see the MCP Server section below).

Response

{
  "name": "coven-ai",
  "version": "1.0.0",
  "description": "Coven AI — scan websites for AI agent readiness across five dimensions.",
  "endpoint": "https://api.covenai.io/mcp",
  "protocol": "jsonrpc-2.0"
}

Authenticated API

All endpoints below require a Bearer API key in the Authorization header. Keys are issued from Mission Control and rate-limited per tier (see Rate Limits).

GET /api/v1/sites Auth Required

List all sites registered to the authenticated account, including their tracking IDs, last-scan timestamps, and current overall scores.

Request

curl -H "Authorization: Bearer caa_..." \
  "https://api.covenai.io/api/v1/sites"

GET /api/v1/sites/:id/stats Auth Required

Aggregated agent-traffic stats for one site: visit counts by platform (OpenAI, Anthropic, Perplexity, Google, Apple, Meta, others), top pages, and trends over the requested time window.

Query Parameters

Name	Type	Required	Description
since	string (ISO 8601)	Optional	Window start. Defaults to 30 days ago.

GET /api/v1/sites/:id/events Auth Required

Raw stream of agent visits for one site. Each event includes the user agent, detected platform, type (training/search/browse), confidence, page URL, and timestamp. Useful for building custom dashboards or feeding agent visits into your own observability tooling.

GET /api/v1/sites/:id/agents Auth Required

Aggregated breakdown of which AI agents are visiting one site, grouped by platform. Includes visit counts, percentage share, and first/last seen timestamps.

GET /api/v1/sites/:id/pages Auth Required

Top pages visited by agents on one site, ranked by total agent visits.

GET /api/v1/sites/:id/citability Auth Required

Latest citability scan for one site — the same five-dimension v2.0.1 result shape as /public/scan, but for the registered site rather than ad-hoc URLs.

POST /api/v1/sites/:id/citability/scan Auth Required

Trigger a fresh citability scan for one registered site. Runs against your tier's quota and rate limit.

GET /api/v1/sites/:id/insights Auth Required

Prioritised list of recommendations for one site, derived from the latest citability scan and agent-traffic patterns.

GET /api/v1/account Auth Required

Returns the authenticated account: id, email, current tier, beta flags, and notification preferences.

GET /api/v1/benchmarks Auth Required

Aggregate benchmarks across the COVEN sample — typical scores per dimension, percentile ranks, and traffic distributions. See /benchmarks/trends for time-series.

GET /api/v1/benchmarks/trends Auth Required

Benchmark time-series — how typical scores have moved over the requested window.

Monitoring

Sites added through Mission Control are scanned weekly (Mondays 03:00 UTC, with the spider refreshing per-site every seven days). Use the authenticated API to read the latest scan and configure webhooks. Open rubric, paid tooling — the underlying methodology is open at /methodology; the monitoring layer is the paid tooling that runs it for you on a schedule.

Free during beta — monitoring is gated by paid tier when tiers activate; during the public beta it is reachable on invitation-only API keys. Pricing earns its way in. Join the waitlist to request access.

To list sites on your account, use GET /api/v1/sites. New sites are added via Mission Control during beta; programmatic site registration opens with the paid Optimisation tier.

GET /api/v1/sites/:id/citability

Get the latest scan result for one monitored site — the same five-dimension v2.0.1 shape as /public/scan. Issues, passes, and research signals included.

Response 200

{
  "siteId": 42,
  "methodologyVersion": "2.0.1",
  "overallScore": 74,
  "grade": "B",
  "dimensions": [
    { "id": "structure",        "weight": 0.25, "score": 82 },
    { "id": "citability",       "weight": 0.25, "score": 71 },
    { "id": "discoverability",  "weight": 0.15, "score": 68 },
    { "id": "agent_interface",  "weight": 0.20, "score": 75 },
    { "id": "transactability",  "weight": 0.15, "score": 70 }
  ],
  "researchSignals": [
    { "id": "agent_correlation", "weight": 0, "score": 62 }
  ],
  "scannedAt": "2026-04-28T08:00:00.000Z"
}

Webhook Alerts

Manage webhooks via /api/v1/webhooks (list, create, update, delete, test). When a score crosses your configured threshold on a scheduled scan, COVEN POSTs to your registered 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.

MCP Server

The Model Context Protocol (MCP) is an open standard that lets AI agents discover and call external tools natively. COVEN is available as an MCP server, making it natively callable by Claude, GPT-4o, and any other MCP-compatible AI agent.

MCP Endpoint

MCP Server URL https://api.covenai.io/mcp

Discovery Files

https://covenai.io/.well-known/agent.json
https://covenai.io/.well-known/mcp.json

Available Tools

Tool Name	Description	Auth Required
scan_website	Scan any URL across the five scored agent-readability dimensions — Structure, Citability, Discoverability, Agent Interface, Transactability (Agent Correlation reported separately as a research signal at 0% weight)	Bearer key required
get_citability_score	Get citability score and breakdown for a URL — how likely AI agents are to cite this page	Bearer key required

Configure in Claude Desktop

{
  "mcpServers": {
    "coven-ai": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "env": {
        "MCP_SERVER_URL": "https://api.covenai.io/mcp",
        "AUTHORIZATION": "Bearer caa_your_key_here"
      }
    }
  }
}

Or simply point any MCP client at the endpoint — COVEN's tools/list response is fully spec-compliant.

API Tiers

Free during beta. Pricing earns its way in. The tiers below are what API access maps to once paid plans activate; today the public scan endpoint is openly reachable, and authenticated /api/v1/* endpoints are issued on invitation.

Tier	Rate Limit	API Access	Best For
Public scan	Per-IP, lenient	`POST /api/public/scan` on aa.covenai.io	Single-URL evaluations, embeddable demos
Intelligence	100 calls/hour	All `/api/v1/*` endpoints + MCP	Dashboards, integrations, agent-built tools
Optimisation	1000 calls/hour	All endpoints + scheduled monitoring + webhooks	High-volume production, agencies, scheduled scans

Get your API key → Open Mission Control. During beta, keys are invitation-only — join the waitlist.

Rate Limits

Authenticated endpoints are rate-limited per API key on a rolling hourly window: 100 calls/hour on Intelligence, 1000 calls/hour on Optimisation. When you exceed the limit, the API returns 429 Too Many Requests. Back off and retry after the window resets.

Rate limit headers are included in every response:

        X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1711497600
      

Error Reference

HTTP Status Codes

Status	Meaning
200	Success
400	Bad request — check parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — tier too low for this endpoint
429	Rate limit exceeded — back off and retry
500	Server error — check status page

JSON-RPC Error Codes (MCP)

Code	Meaning
-32001	Unauthorized — valid API key required
-32002	Forbidden — pro/agent tier required
-32602	Invalid params — check tool arguments

COVEN AI Developer API

Overview

REST API

MCP Server

OpenAPI Spec

Live Demo

Authentication

Public Endpoints

Body Parameters

Request

Response

Response

Response

Authenticated API

Request

Query Parameters

Monitoring

Response 200

Webhook Alerts

Payload

MCP Server

MCP Endpoint

Discovery Files

Available Tools

Configure in Claude Desktop

API Tiers

Rate Limits

Error Reference

HTTP Status Codes

JSON-RPC Error Codes (MCP)