Introduction

The DDactic API allows you to programmatically interact with our DDoS vulnerability assessment platform. Use it to automate domain verification, trigger scans, retrieve reports, and integrate findings into your security workflows.

Beta Notice: The API is currently in beta. Some endpoints may change. We recommend pinning to specific API versions.

Base URL

https://api.ddactic.net/v1

API Versioning

The API version is included in the URL path. Current version is v1. When we release breaking changes, we'll create a new version and deprecate the old one with a 12-month migration period.

Authentication

All API requests require authentication using an API key. Include your key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Getting an API Key

Generate API keys from your dashboard at Settings > API Keys.

Key Types

Type Permissions Use Case
read Read-only access to domains, scans, reports Dashboards, monitoring
write Full access including triggering scans CI/CD integration
admin Organization management, user management Admin tools
Security: Never expose API keys in client-side code. Use server-side requests or environment variables.

Rate Limits

Rate limits vary by plan and endpoint:

Plan Requests/minute Scans/day
Free 60 5
Pro 300 50
Enterprise 1000 Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1702900000

Error Handling

The API uses standard HTTP status codes and returns JSON error responses:

{
  "error": {
    "code": "invalid_domain",
    "message": "Domain not verified",
    "details": {
      "domain": "example.com"
    }
  }
}

Common Error Codes

Code HTTP Status Description
unauthorized 401 Invalid or missing API key
forbidden 403 Insufficient permissions
not_found 404 Resource doesn't exist
rate_limited 429 Too many requests
invalid_domain 400 Domain not verified or invalid
scan_in_progress 409 Scan already running for domain

Domains

Manage domains for scanning and monitoring.

GET /domains

List all verified domains in your organization.

Query Parameters

Parameter Type Description
limit integer Max results (default 50, max 100)
offset integer Pagination offset

Response

{
  "domains": [
    {
      "id": "dom_abc123",
      "name": "example.com",
      "verified": true,
      "last_scan": "2025-12-17T10:30:00Z",
      "risk_score": 4.2
    }
  ],
  "total": 15
}
POST /domains

Add a new domain for verification.

Request Body

Parameter Type Description
domain required string Domain name (e.g., "example.com")

Response

{
  "id": "dom_abc123",
  "domain": "example.com",
  "verification": {
    "method": "dns_txt",
    "record": "ddactic-verify=abc123xyz"
  }
}

Scans

Trigger and monitor DDoS vulnerability scans.

POST /scans

Start a new scan for a verified domain.

Request Body

Parameter Type Description
domain_id required string Domain ID from /domains
type string Scan type: "passive" (default), "active", "full"
webhook_url string URL to receive completion webhook

Response

{
  "scan_id": "scn_xyz789",
  "status": "queued",
  "estimated_time": 300
}
GET /scans/{scan_id}

Get scan status and results.

Response

{
  "scan_id": "scn_xyz789",
  "domain": "example.com",
  "status": "completed",
  "started_at": "2025-12-17T10:30:00Z",
  "completed_at": "2025-12-17T10:35:00Z",
  "risk_score": 4.2,
  "findings_count": {
    "critical": 1,
    "high": 3,
    "medium": 8,
    "low": 12
  }
}

Reports

Download scan reports in various formats.

GET /scans/{scan_id}/report

Get the full report for a completed scan.

Query Parameters

Parameter Type Description
format string "json" (default), "pdf", "html"
type string "executive", "technical", "full"

Findings

Access individual vulnerability findings.

GET /scans/{scan_id}/findings

List all findings from a scan with remediation guidance.

Response

{
  "findings": [
    {
      "id": "F-001",
      "severity": "critical",
      "title": "Origin IP Exposed",
      "description": "Origin server directly accessible...",
      "affected_asset": "192.0.2.1",
      "remediation": {
        "summary": "Restrict origin access to CDN IPs",
        "cli_commands": [
          "iptables -I INPUT -p tcp --dport 443 -s CDN_IP_RANGE -j ACCEPT"
        ]
      }
    }
  ]
}

Webhooks

Receive real-time notifications about scan events.

Webhook Events

Event Description
scan.started Scan has begun
scan.completed Scan finished successfully
scan.failed Scan encountered an error
finding.new New critical/high finding discovered

Webhook Payload

{
  "event": "scan.completed",
  "timestamp": "2025-12-17T10:35:00Z",
  "data": {
    "scan_id": "scn_xyz789",
    "domain": "example.com",
    "risk_score": 4.2
  }
}

Signature Verification

Verify webhook authenticity using the X-DDactic-Signature header:

// Node.js example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

SDKs & Libraries

Official and community SDKs (coming soon):

  • Python: pip install ddactic (planned)
  • Node.js: npm install @ddactic/sdk (planned)
  • Go: go get github.com/ddactic/ddactic-go (planned)
CLI Tool: For command-line access, use our CLI: curl -L https://ddactic.net/cli/install | sh

Code Examples

Python: Run a Scan

import requests

API_KEY = "your_api_key"
BASE_URL = "https://api.ddactic.net/v1"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Start scan
response = requests.post(
    f"{BASE_URL}/scans",
    headers=headers,
    json={"domain_id": "dom_abc123", "type": "passive"}
)
scan = response.json()
print(f"Scan started: {scan['scan_id']}")

cURL: Get Report

curl -X GET "https://api.ddactic.net/v1/scans/scn_xyz789/report?format=pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o report.pdf

JavaScript: Poll for Completion

async function waitForScan(scanId) {
  const headers = { 'Authorization': `Bearer ${API_KEY}` };
  
  while (true) {
    const res = await fetch(
      `https://api.ddactic.net/v1/scans/${scanId}`,
      { headers }
    );
    const data = await res.json();
    
    if (data.status === 'completed') {
      return data;
    }
    
    await new Promise(r => setTimeout(r, 5000));
  }
}