API Reference

All CyberDoc API endpoints are served at the /api/ path prefix. Endpoints are grouped into public (no auth) and authenticated (session cookie required).

Base URL. All endpoints are relative to the deployment origin. For production: https://your-cyberdoc-domain.com/api/

Authentication

Type	Applies To	Mechanism
None	Public endpoints	No auth required. Turnstile token may be required for bot protection.
Session	Auth endpoints	`cyberdoc_session` cookie. Set on login via `/api/auth/email/login` or magic link.
Session + Plan	Billing-gated endpoints	Session cookie + active Business or Enterprise subscription.

Common Response Format

All endpoints return JSON. Successful responses include the data directly. Errors use a standard error envelope:

// Success (varies by endpoint)
{ "scan_id": "scan_abc123", "status": "created" }

// Error
{
  "error": "Not found",
  "code": "SCAN_NOT_FOUND",
  "status": 404
}

Public Endpoints

POST /api/lead

Create a new scan lead (initiates a CyberDoc session).

Property	Detail
Auth	None (Turnstile token required)
Content-Type	`application/json`

Request body:

{
  "name": "Jane Smith",
  "email": "[email protected]",
  "domain": "example.com",        // optional
  "turnstile_token": "0.xxx..."   // Cloudflare Turnstile response
}

Response (201):

{
  "scan_id": "scan_a1b2c3d4",
  "status": "IN PROGRESS",
  "created_at": "2026-03-28T10:30:00Z"
}

POST /api/report

Submit scan results (GP answers and/or pen test findings) for a scan session.

Property	Detail
Auth	None
Content-Type	`application/json`

Request body:

{
  "scan_id": "scan_a1b2c3d4",
  "gp_answers": {
    "device": 0,
    "purpose": 2,
    "password_manager": 1,
    "password_reuse": 2,
    "two_factor": 0,
    "updates": 1,
    "phishing": 0,
    "wifi": 2,
    "backups": 1,
    "social_privacy": 0
  },
  "pentest_results": [
    {
      "id": "fingerprint",
      "name": "Browser Fingerprint Analysis",
      "severity": "medium",
      "finding": "Browser is uniquely identifiable across 94% of tested configurations"
    }
    // ... additional results
  ]
}

Response (200):

{
  "scan_id": "scan_a1b2c3d4",
  "status": "PEN TEST COMPLETE",
  "overall_score": 62,
  "categories": {
    "passwords": { "score": 3, "max": 6 },
    "authentication": { "score": 1, "max": 3 },
    // ...
  }
}

POST /api/consent

Record pen test consent with audit trail.

Property	Detail
Auth	None (Turnstile token required)
Content-Type	`application/json`

Request body:

{
  "scan_id": "scan_a1b2c3d4",
  "consent_type": "pentest",
  "turnstile_token": "0.xxx..."
}

Response (201):

{
  "consent_id": "con_x1y2z3",
  "scan_id": "scan_a1b2c3d4",
  "type": "pentest",
  "ip": "203.0.113.10",
  "timestamp": "2026-03-28T10:32:15Z"
}

POST /api/voice/session

Create a new voice agent session.

Property	Detail
Auth	None
Content-Type	`application/json`

Request body:

{
  "scan_id": "scan_a1b2c3d4",
  "voice": "drew"   // optional, default "drew"
}

Response (201):

{
  "session_id": "vs_m1n2o3",
  "ws_url": "wss://voice.x.ai/v1/agent/session/vs_m1n2o3",
  "voice": "drew",
  "expires_at": "2026-03-28T11:02:15Z"
}

POST /api/voice/end

End a voice session and save the transcript.

Request body:

{
  "session_id": "vs_m1n2o3",
  "transcript": [
    { "role": "agent", "text": "Hello, I'm CyberDoc...", "ts": 0 },
    { "role": "user", "text": "Hi, can you explain...", "ts": 4.2 }
  ],
  "duration_seconds": 245
}

Response (200):

{
  "voice_log_id": "vl_p1q2r3",
  "cost_usd": 0.20
}

POST /api/deepscan

Initiate a server-side Lab scan on a target domain.

Property	Detail
Auth	None (scan must be associated with a valid lead)
Content-Type	`application/json`

Request body:

{
  "scan_id": "scan_a1b2c3d4",
  "target": "example.com"
}

Response (202):

{
  "scan_id": "scan_a1b2c3d4",
  "status": "LAB SCAN IN PROGRESS",
  "estimated_duration_seconds": 300
}

GET /api/deepscan/:scan_id

Poll for Lab scan progress and results.

Response (200):

{
  "scan_id": "scan_a1b2c3d4",
  "status": "COMPLETE",
  "tools": {
    "nmap": { "status": "complete", "findings": [...], "raw": "..." },
    "nuclei": { "status": "complete", "findings": [...], "raw": "..." },
    // ...
  },
  "completed_at": "2026-03-28T10:37:42Z"
}

POST /api/analyze

Send all scan results to Anthropic Claude for AI diagnosis.

Request body:

{
  "scan_id": "scan_a1b2c3d4"
}

Response (200):

{
  "scan_id": "scan_a1b2c3d4",
  "diagnosis": "Based on your scan results, your overall cyber health...",
  "prescriptions": [
    {
      "priority": 1,
      "category": "credentials",
      "text": "Your email was found in 7 data breaches...",
      "severity": "critical"
    }
    // ...
  ],
  "overall_assessment": "NEEDS ATTENTION",
  "model": "claude-sonnet-4-20250514"
}

Rate Limits

Endpoint	Limit	Window
Lead capture	10 requests	per minute per IP
Breach check	100 requests	per day per IP
Social check	30 requests	per hour per IP
AI Analysis	10 requests	per hour per IP
Voice	5 sessions	per hour per IP