REST API

Overview

Base URL: https://cavexia.com

All API endpoints accept and return application/json. Authenticated endpoints require an Authorization: Bearer <api_key> header. Anonymous endpoints are rate-limited by IP; authenticated requests are rate-limited by API key and plan.

Authentication

Generate an API key from Dashboard → Settings → API keys. Include it as a Bearer token on every authenticated request.

curl https://cavexia.com/api/scan \
  -H "Authorization: Bearer cvx_live_xxxxxxxxxxxxxxxx" \
  -G --data-urlencode 'config={"mcpServers":{"my-server":{"command":"npx","args":["-y","my-mcp"]}}}'

API keys are prefixed cvx_live_ for production and cvx_test_ for test mode. Test-mode keys count against the same quota but return synthetic data.

Rate limits

Rate limits are enforced per API key (authenticated) or per IP (anonymous). When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header (seconds).

Rate limit headers are included on every response: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix timestamp).

Scan an MCP config

Runs the full detection engine against a JSON MCP config. Anonymous requests are capped at 30 scans/day per IP for anonymous requests; authenticated requests use your plan's monthly API quota.

Query parameters

Example — anonymous

curl https://cavexia.com/api/scan \
  -G --data-urlencode 'config={"mcpServers":{"filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/tmp"]}}}'

Example — authenticated

curl https://cavexia.com/api/scan \
  -H "Authorization: Bearer cvx_live_xxxxxxxxxxxxxxxx" \
  -G --data-urlencode 'config={"mcpServers":{"filesystem":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/tmp"]}}}'

Response (200)

{
  "ok": true,
  "findings": [
    {
      "category": "toolPoisoning",
      "severity": "high",
      "server": "filesystem",
      "message": "Tool description contains prompt injection pattern",
      "evidence": "...",
      "cve": null
    }
  ],
  "summary": {
    "total": 1,
    "critical": 0,
    "high": 1,
    "medium": 0,
    "low": 0,
    "info": 0
  },
  "scanId": "scn_01hxxxxxxx",
  "scannedAt": "2026-05-20T12:00:00.000Z"
}

List threat-intel items

Returns the paginated threat-intel feed — CVE advisories, tool-poisoning disclosures, and malicious package reports. Available to all plans including unauthenticated requests (read-only).

Query parameters

Example

curl "https://cavexia.com/api/intel?category=cve&severity=critical&per_page=5"

Response (200)

{
  "items": [
    {
      "slug": "cve-2024-12345-mcp-server-rce",
      "title": "CVE-2024-12345: RCE in example-mcp-server ≤ 1.2.3",
      "category": "cve",
      "severity": "critical",
      "publishedAt": "2024-11-01T00:00:00.000Z",
      "summary": "Remote code execution via crafted tool response."
    }
  ],
  "total": 142,
  "page": 1,
  "per_page": 5
}

Get a single intel item

Returns the full detail record for a single threat-intel item identified by its slug.

Path parameters

Example

curl https://cavexia.com/api/intel/cve-2024-12345-mcp-server-rce

Response (200)

{
  "slug": "cve-2024-12345-mcp-server-rce",
  "title": "CVE-2024-12345: RCE in example-mcp-server ≤ 1.2.3",
  "category": "cve",
  "severity": "critical",
  "publishedAt": "2024-11-01T00:00:00.000Z",
  "updatedAt": "2024-11-15T09:00:00.000Z",
  "summary": "Remote code execution via crafted tool response.",
  "description": "Full markdown description...",
  "affectedPackages": ["example-mcp-server"],
  "cvss": 9.8,
  "cveId": "CVE-2024-12345",
  "references": [
    "https://nvd.nist.gov/vuln/detail/CVE-2024-12345"
  ],
  "fixedIn": "1.2.4"
}

Submit an intel report

Submit a new vulnerability or malicious-package report for triage by the Cavexia team. Submissions are reviewed before being published to the feed. Authentication is required.

Request body (JSON)

Example

curl -X POST https://cavexia.com/api/intel/submissions \
  -H "Authorization: Bearer cvx_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Prompt injection in example-mcp-server tool descriptions",
    "category": "toolPoisoning",
    "severity": "high",
    "description": "The `list_files` tool description in example-mcp-server injects...",
    "affectedPackages": ["example-mcp-server"],
    "references": ["https://github.com/example/mcp-server/issues/99"]
  }'

Response (201)

{
  "id": "sub_01hxxxxxxx",
  "status": "pending_review",
  "message": "Submission received. The Cavexia team will review within 48 hours.",
  "submittedAt": "2026-05-20T12:00:00.000Z"
}

List monitored items

Returns the authenticated user's registered monitoring targets. Requires a Pro, Team, or Enterprise plan.

Example

curl https://cavexia.com/api/user/monitored-items \
  -H "Authorization: Bearer cvx_live_xxxxxxxxxxxxxxxx"

Response (200)

{
  "items": [
    {
      "id": "mon_01hxxxxxxx",
      "label": "prod-claude-config",
      "config": {"mcpServers": {"...": "..."}},
      "scanFrequencyHours": 1,
      "lastScannedAt": "2026-05-20T11:00:00.000Z",
      "lastFindingsCount": 0,
      "createdAt": "2026-05-01T00:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50
}

Register a monitored item

Registers a new MCP config for continuous monitoring. Cavexia will re-scan it at your plan's scan frequency and send alerts when new findings appear. Requires Pro or higher.

Request body (JSON)

Example

curl -X POST https://cavexia.com/api/user/monitored-items \
  -H "Authorization: Bearer cvx_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "prod-claude-config",
    "config": {
      "mcpServers": {
        "filesystem": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
        }
      }
    },
    "alertOnSeverity": ["critical", "high", "medium"]
  }'

Response (201)

{
  "id": "mon_01hxxxxxxx",
  "label": "prod-claude-config",
  "scanFrequencyHours": 1,
  "alertOnSeverity": ["critical", "high", "medium"],
  "createdAt": "2026-05-20T12:00:00.000Z"
}

Error codes

All errors use standard HTTP status codes with a JSON body containing a machine-readable code and a human-readable message.

Error response shape

{
  "ok": false,
  "code": "rate_limited",
  "message": "You have exceeded 10 scans/hour on the Free plan.",
  "retryAfter": 3600
}