CyberVault API Reference

Authentication

Authenticate your API requests by including your secret API key in the `Authorization` header. All API keys are scoped to your organization and must be kept secure.

Header Format

Authorization: Bearer cv_live_sk_8xK9mP2qL5vN7wR3yT1zJ4

Keys beginning with cv_live_ are for production environments. Keys beginning with cv_test_ are for sandbox testing and do not trigger real threat scans.

Rate Limiting

API requests are limited to 600 requests per minute per API key. Rate limit headers are included in every response:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the limit resets

Exceeding the limit returns a 429 Too Many Requests status code. Implement exponential backoff for retries.

Core Endpoints

GET /threats/scan

Initiate a real-time threat scan across your monitored assets. Returns scan status and preliminary findings.

Query Parameters

Parameter	Type	Required	Description
target_ip	string	Required	IP address or CIDR range to scan
depth	enum	Optional	Scan depth: `quick`, `standard`, `deep`
include_vulns	boolean	Optional	Include CVE database cross-referencing

                                
                                
                                
                            

                            curl -X GET "https://api.cybervault.io/v1/threats/scan?target_ip=192.168.1.0/24&depth=standard" \n-H "Authorization: Bearer cv_live_sk_..."
                            import requests

response = requests.get("https://api.cybervault.io/v1/threats/scan",
    params={"target_ip": "192.168.1.0/24", "depth": "standard"},
    headers={"Authorization": "Bearer cv_live_sk_..."}
)
print(response.json())
                            const axios = require('axios');

const response = await axios.get('https://api.cybervault.io/v1/threats/scan', {
  params: { target_ip: '192.168.1.0/24', depth: 'standard' },
  headers: { 'Authorization': 'Bearer cv_live_sk_...' }
});
console.log(response.data);
                        

Response Example

                            JSON
                            
                        
{
  "scan_id": "sc_9f8e7d6c5b4a",
  "status": "completed",
  "threats_found": 2,
  "findings": [
    {
      "type": "open_port",
      "severity": "medium",
      "details": "Port 22 exposed to public internet",
      "cve": null
    },
    {
      "type": "vulnerable_service",
      "severity": "critical",
      "details": "Apache Struts 2.5.10 detected",
      "cve": "CVE-2017-5638"
    }
  ],
  "timestamp": "2025-01-15T08:32:11Z"
}

POST /incidents/report

Create a new security incident ticket. Triggers automated triage and notifies your security team via configured channels.

Request Body

Field	Type	Required	Description
title	string	Required	Brief incident summary
severity	enum	Required	`low`, `medium`, `high`, `critical`
description	string	Required	Detailed incident report
affected_systems	array	Optional	List of asset IDs or IPs

GET /compliance/status

Retrieve current compliance posture across SOC 2, ISO 27001, HIPAA, and GDPR frameworks. Returns control mapping and gap analysis.

Error Codes

CyberVault uses standard HTTP status codes. Errors include a JSON body with detailed information.

200 OK

Request succeeded

400 Bad Request

Invalid parameters or malformed JSON

401 Unauthorized

Missing or invalid API key

403 Forbidden

Insufficient permissions for resource

404 Not Found

Resource does not exist

429 Rate Limited

Too many requests, backoff required

500 Server Error

Internal failure, retry with exponential backoff

Error Response Format
{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is expired or invalid."
    "documentation_url": "https://docs.cybervault.io/errors/invalid_api_key"
  }
}

SDKs & Libraries

Official client libraries are available for major languages. All SDKs handle authentication, retries, and pagination automatically.

Language	Package	Documentation
Python	`pip install cybervault-sdk`	docs
Node.js	`npm install @cybervault/node`	docs
Go	`go get github.com/cybervault/sdk-go`	docs
Ruby	`gem install cybervault`	docs

Webhooks

Configure webhook endpoints to receive real-time notifications for threat detections, incident updates, and compliance changes. All payloads are signed with HMAC-SHA256 using your webhook secret.

Webhook Signature Verification
import hmac, hashlib

def verify(payload, signature, secret):
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)