API Reference

Welcome to the CyberVault API. This documentation covers everything you need to integrate our threat intelligence, scanning, and security automation services into your infrastructure. All API requests must be made over HTTPS.

Base URL: https://api.cybervault.io/v1
All responses are returned in JSON format. Timeouts default to 30 seconds. Large payloads should use chunked transfer encoding.

Authentication

Authenticating API requests is done using API keys. You can generate and manage your keys in the CyberVault Dashboard under Settings → API Access. Never expose your secret keys in client-side code.

Include your API key in the Authorization header:

# Example Request
curl -X GET https://api.cybervault.io/v1/threats/feed \
  -H "Authorization: Bearer cv_live_8x92m...p4z1" \
  -H "Content-Type: application/json"
                    

POST /threats/analyze

Submits a URL, IP address, file hash, or payload for immediate threat analysis. Returns a comprehensive risk score, classification, and recommended actions.

Request Body

Parameter	Type	Required	Description
target	string	Required	URL, IP, MD5/SHA256 hash, or raw payload
mode	string	Optional	`quick`, `deep`, or `sandbox`. Default: `quick`
metadata	object	Optional	Custom key-value pairs for tagging

Response

{
  "request_id": "req_8f3a2c1d",
  "threat_score": 0.94,
  "classification": "malicious",
  "family": "cobalt_strike",
  "indicators": [
    "c2_beacon",
    "obfuscated_strings"
  ],
  "action": "block_and_alert",
  "timestamp": "2025-04-12T08:41:00Z"
}
                    

POST /scans/initialize

Creates a new asynchronous security scan for a target environment. Scans support network ranges, cloud resources, and container registries. Use webhooks or polling to track progress.

Request Body

Parameter	Type	Required	Description
targets	array	Required	List of CIDR ranges, domains, or ARNs
profile	string	Optional	Scan template: `standard`, `compliance`, `pentest`
max_duration	integer	Optional	Max scan time in minutes (default: 60)

Response

{
  "scan_id": "scan_9x4m2k1p",
  "status": "queued",
  "estimated_completion": "2025-04-12T09:15:00Z",
  "webhook_url": "https://api.cybervault.io/v1/scans/scan_9x4m2k1p/events"
}
                    

Error Handling

CyberVault uses standard HTTP status codes to indicate success or failure. Codes 2xx indicate success, 4xx indicate client errors, and 5xx indicate server errors.

Code	Meaning	Description
400	Bad Request	Malformed JSON or missing required parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Key lacks permissions for this endpoint
429	Too Many Requests	Rate limit exceeded. Retry after X-RateLimit-Reset
500	Server Error	Internal processing failure. Contact support if persistent.

Error Format: All errors return a JSON body with error_code, message, and optionally details and trace_id for support debugging.

Rate Limits & Pagination

API calls are limited based on your plan tier. Standard plans allow 1,000 requests/minute, while Enterprise plans support up to 10,000 requests/minute. Burst traffic is automatically queued.

Rate limit headers are included in every response:

X-RateLimit-Limit: Max requests per window
X-RateLimit-Remaining: Remaining requests
X-RateLimit-Reset: Unix timestamp when limit resets

Endpoints returning collections support cursor-based pagination:

curl "https://api.cybervault.io/v1/threats/feed?limit=50&cursor=eyJpZCI6MTAyNH0"
                    