API Documentation

Build with Vysiro API

Integrate domain security scanning, TrustScore monitoring, and automated auto-fix into your applications with our RESTful API and MCP server.

Quick Start API Reference

API is in Beta. Endpoints and response formats are subject to change.

Quick Start

Get up and running with the Vysiro API in minutes

Authentication

All API requests require a Bearer token. Get your API key from the settings.

HTTP Header

Authorization: Bearer YOUR_API_KEY

Run Your First Scan

cURL

curl -X POST https://www.vysiro.com/api/v1/scan \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com" }'

Response

JSON Response

{
  "scanId": "scan_1709312400_a1b2c3",
  "domain": "example.com",
  "trustScore": {
    "score": 620,
    "maxScore": 1000,
    "percentage": 82.7,
    "grade": "A",
    "categories": [
      { "id": "dmarc", "name": "DMARC", "maxPoints": 150, "earnedPoints": 120 },
      { "id": "spf", "name": "SPF", "maxPoints": 100, "earnedPoints": 95 },
      { "id": "ssl", "name": "SSL/TLS", "maxPoints": 100, "earnedPoints": 100 }
    ]
  },
  "recommendations": [
    { "title": "Upgrade DMARC to p=reject", "impact": "high" }
  ],
  "scanDurationMs": 2340,
  "scannedAt": "2026-03-01T10:30:00Z"
}

Node.js / TypeScript Example

TypeScript

const API_KEY = process.env.VYSIRO_API_KEY;
const BASE = 'https://www.vysiro.com/api';

// Run a full domain scan
const res = await fetch(`${BASE}/v1/scan`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ domain: 'example.com' }),
});

const scan = await res.json();
console.log(`TrustScore: ${scan.trustScore.score}/1000`);
console.log(`Grade: ${scan.trustScore.grade}`);

// Public endpoint - no auth required
const score = await fetch(`${BASE}/v1/score/example.com`);
const data = await score.json();
console.log(`Quick Score: ${data.score}/1000 (${data.grade})`);

API Endpoints

Base URL: https://www.vysiro.com/api

POST/v1/scanRun a full domain scan (DNS + SSL + TrustScore)

GET/v1/score/{domain}Get TrustScore for any domain (public, rate-limited)

GET/v1/historyGet scan history with pagination (?domain=&limit=)

GET/v1/report/{id}Retrieve a shareable scan report by ID

POST/v1/api-keysCreate, list, or revoke API keys

POST/v1/chatAI security chat (SSE streaming)

POST/v1/trust-coachGet AI-powered fix guidance for a domain

GET/v1/threat-intelVirusTotal threat intelligence lookup

GET/v1/benchmarksIndustry benchmark percentile rankings (Pro+)

POST/v1/fixesLog and retrieve DNS fix events

SDKs & Tools

Official client libraries and MCP integration. Use the REST API directly or connect via our MCP server for AI agents.

Node.js / TypeScript

Coming Soon

npm install @vysiro/sdk

Python

Coming Soon

pip install vysiro

Go

Coming Soon

go get github.com/vysiro/go-sdk

MCP Server

https://www.vysiro.com/api/mcp

MCP Server

AI Agent Integration

Connect AI agents to Vysiro via the MCP server. Scan domains, check TrustScores, compare protocols, and trigger fixes autonomously from Claude Code, Cursor, VS Code, or any MCP-compatible client.

vysiro_scan - Run a full domain scan
vysiro_score - Get TrustScore for a domain
vysiro_check_protocol - Check a specific protocol (DMARC, SPF, etc.)
vysiro_compare - Compare security across domains

MCP Configuration (Claude Code / Cursor)

{
  "mcpServers": {
    "vysiro": {
      "url": "https://www.vysiro.com/api/mcp"
    }
  }
}

Public Endpoints

GET /api/v1/score/{domain} - Public TrustScore, no auth required
/openapi.json - OpenAPI specification
POST /api/v1/api-keys - API key management

Rate Limits

API rate limits by plan. Exceeded limits return HTTP 429.

Plan	Monthly Limit	Burst Rate
Free	100 requests/month	5/minute
Starter ($29/mo)	5,000 requests/month	20/minute
Growth ($99/mo)	10,000 requests/month	200/minute
MSP Partner	Custom	Custom

Webhooks

Receive real-time notifications when events occur in your account. Register a webhook endpoint via POST /v1/webhooks.

Event Types

scan.completedFired when a domain scan finishes{ scanId, domain, trustScore, grade }

score.changedFired when a domain TrustScore changes{ domain, previousScore, newScore, delta }

certificate.expiringFired 30/14/7 days before SSL cert expires{ domain, expiresAt, daysRemaining }

compliance.violationFired when a compliance check fails{ domain, framework, check, severity }

agent.alertFired when AgentShield detects a threat{ domain, threatType, severity, details }

Signature Verification

Every webhook request includes an X-Vysiro-Signature header. Verify it using HMAC-SHA256 with your webhook secret:

TypeScript

import { createHmac } from 'crypto';

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return signature === `sha256=${expected}`;
}

// In your webhook handler:
const isValid = verifyWebhook(rawBody, req.headers['x-vysiro-signature'], WEBHOOK_SECRET);
if (!isValid) return new Response('Invalid signature', { status: 401 });

Retry Policy

3 retries with exponential backoff (10s, 60s, 300s)
Your endpoint must respond with 2xx within 10 seconds
After 3 failures, the webhook is disabled and you are notified via email

Error Codes

All errors return a consistent JSON structure with an HTTP status code.

Error Response Shape

{
  "error": "Rate limit exceeded",
  "code": 429,
  "requestId": "req_1709312400_x7k2m"
}

Code	Name	Description	Resolution
400	Bad Request	Missing or invalid parameters	Check request body matches the endpoint schema
401	Unauthorized	Missing or invalid API key	Include valid Bearer token in Authorization header
403	Forbidden	API key lacks required scope or tier	Upgrade plan or request additional scopes
404	Not Found	Resource does not exist	Verify the domain/scanId/reportId is correct
409	Conflict	Scan already in progress for this domain	Wait for the current scan to complete
429	Too Many Requests	Rate limit exceeded	Back off and retry after Retry-After header value
500	Internal Server Error	Unexpected server error	Retry with exponential backoff; contact support if persistent
503	Service Unavailable	Upstream resolver temporarily unavailable	Retry in 30 seconds

Start Building Today

Get your API key and start integrating domain security into your applications. Free tier includes 10 requests per day.

Get API Key