CyberVault API Documentation

Welcome to the official API documentation for CyberVault. This RESTful API enables programmatic access to our AI-driven threat detection, incident response, and compliance monitoring systems. All requests require authentication via API keys.

Base URL & Versioning

All API requests are made to:

https://api.cybervault.io/v1

The API is versioned via the URL path. We maintain backward compatibility for minor version updates. Breaking changes will be announced with a new major version.

Authentication

CyberVault uses Bearer token authentication. Include your API key in the `Authorization` header of every request.

Authorization: Bearer cv_live_9x8f7g6h5j4k3l2m1n0p

🔒 Security Note: Never expose API keys in client-side code or public repositories. Use environment variables or a secure vault.

Rate Limits

Plan	Requests / Minute	Burst Limit
Starter	60	100
Professional	300	500
Enterprise	Unmetered	Custom

Exceeding limits returns a 429 Too Many Requests response with a Retry-After header.

Core Endpoints

GET /v1/health System Health Check

Returns the current operational status of the CyberVault platform and active threat feeds.

                                
                                {
  "status": "operational",
  "version": "v1.2.0",
  "uptime": "99.99%",
  "threat_feeds_active": 14,
  "timestamp": "2025-10-24T14:32:00Z"
}
                            

POST /v1/threats/scan Submit Threat Scan

Submit a URL, IP address, or domain for real-time AI threat analysis. Returns a scan ID for tracking.

Request Body

                                
                                {
  "target": "https://suspicious-domain.example",
  "scan_type": "deep",
  "options": {
    "include_malware": true,
    "include_phishing": true
  }
}
                            

                                
                                {
  "scan_id": "scn_8x7d9f2a1b",
  "status": "processing",
  "eta_seconds": 12,
  "message": "Scan queued successfully."
}
                            

GET /v1/threats/{scan_id} Retrieve Scan Results

Fetch detailed analysis results for a previously submitted scan ID.

                                
                                {
  "scan_id": "scn_8x7d9f2a1b",
  "status": "completed",
  "threat_level": "high",
  "findings": [
    {
      "type": "phishing",
      "confidence": 0.96,
      "details": "Spoofed WHOIS data detected"
    }
  ],
  "recommended_action": "block_and_investigate"
}
                            

POST /v1/incidents/report Report Security Incident

Trigger an immediate incident response workflow. Our SOC team will triage and assign a case manager.

Parameter	Type	Description
`severity` Required	String	One of: `low`, `medium`, `high`, `critical`
`description` Required	String	Brief summary of the observed threat or breach
`affected_systems`	Array	List of compromised endpoints or services
`logs`	Object	Optional JSON payload of relevant firewall/SIEM logs

Error Handling

CyberVault uses standard HTTP status codes. Error responses include a structured JSON body for programmatic handling.

                    
                    {
  "error": {
    "code": "authentication_failed",
    "message": "Invalid or expired API key.",
    "request_id": "req_9f8e7d6c5b4a"
  }
}
                

400Bad Request - Invalid parameters or malformed JSON 401Unauthorized - Missing or invalid API key 403Forbidden - Insufficient permissions for this endpoint 404Not Found - Resource does not exist 429Too Many Requests - Rate limit exceeded 500Internal Server Error - CyberVault system failure

Webhooks

Receive real-time notifications when threat scans complete, incidents are escalated, or compliance statuses change. Configure your webhook endpoints in the CyberVault dashboard.

                    
                    {
  "event": "threat_scan.completed",
  "data": {
    "scan_id": "scn_8x7d9f2a1b",
    "threat_level": "high"
  },
  "signature": "sha256=..."
}
                

SDKs & Libraries

Official SDKs are available for rapid integration:

Python: pip install cybervault-sdk
Node.js: npm install @cybervault/api-client
Go: go get github.com/cybervault/sdk-go
Java: Available via Maven Central