CyberVault API Documentation

Welcome to the official CyberVault API documentation. Our RESTful API provides programmatic access to our AI-powered threat detection, incident response, and compliance automation platforms. Designed for developers and security engineers, the API enables seamless integration into your existing security operations workflow.

💡 Base URL

All API requests should be made to: https://api.cybervault.io/v3

Quick Start Guide

Get up and running with CyberVault in under 5 minutes. Follow these steps to authenticate your first request and scan for active threats.

Sign up at dashboard.cybervault.io and navigate to Settings → API Keys
Generate a new service account with threat:read and response:write scopes
Copy your secret key and store it securely (never commit to version control)
Make your first API call to verify connectivity

bash

# Verify API connectivity
curl -X GET https://api.cybervault.io/v3/system/health \\
  -H "Authorization: Bearer cv_live_sk_8f3j29d..." \\
  -H "Content-Type: application/json"

A successful response will return a 200 OK with your tenant ID and active status:

json

{
  "status": "operational",
  "tenant_id": "tv_9a8b7c6d5e4f",
  "environment": "production",
  "timestamp": "2025-01-15T08:42:11Z"
}

Authentication

CyberVault uses Bearer token authentication. All API requests must include a valid API key in the Authorization header. Keys are scoped to specific permissions and can be rotated or revoked at any time from your dashboard.

⚠️ Security Warning

Never expose API keys in client-side code, public repositories, or browser console. Use environment variables or secret managers (e.g., AWS Secrets Manager, HashiCorp Vault) for production deployments.

Key Formats

Prefixed	Environment	Access Level
`cv_live_sk_...`	Production	Full API access
`cv_test_sk_...`	Sandbox	Restricted, mock responses
`cv_read_sk_...`	Production	Read-only endpoints

Headers

http

Authorization: Bearer cv_live_sk_8f3j29d...  
X-Request-ID: req_abc123def456  # Optional, for tracing  
Content-Type: application/json

Endpoints Overview

The CyberVault API follows REST conventions. Resources are nested logically, and pagination is cursor-based for large datasets. All responses return JSON with consistent error structures.

Common Parameters

Parameter	Type	Description
limit	integer	Max items per page (default: 50, max: 200)
cursor	string	Pagination cursor from previous response
sort	string	Sort field + direction (e.g., `created_at:desc`)
filter	object	JSON filter object for advanced querying

Threat Detection

Submit network traffic, file hashes, or endpoint telemetry for real-time AI analysis. The engine returns severity scores, MITRE ATT&CK mappings, and recommended containment actions.

`POST /v3/threats/analyze`

Submit telemetry data for threat classification.

Request Body

json

{
  "type": "endpoint_telemetry",
  "payload": {
    "process_name": "svchost.exe",
    "pid": 4892,
    "network_connections": [
      { "dst_ip": "198.51.100.42", "port": 4444, "protocol": "TCP" }
    ],
    "hash_sha256": "a]b]c]..."
  }
}

✅ Response Example

Successful analysis returns a 201 Created with threat assessment ID and immediate risk score.

Rate Limits & Pagination

API requests are limited to protect infrastructure integrity. Limits vary by plan tier and endpoint criticality.

Plan	Read Endpoints	Write Endpoints	Burst Allowance
Starter	60 req/min	20 req/min	±15%
Professional	300 req/min	100 req/min	±20%
Enterprise	Custom	Custom	Dedicated allocation

When approaching limits, the API returns 429 Too Many Requests with a Retry-After header. Implement exponential backoff for resilience.

Error Codes

CyberVault uses standard HTTP status codes alongside application-specific error payloads for debugging.

Code	Meaning	Resolution
`400`	Bad Request	Validate JSON schema and required fields
`401`	Unauthorized	Check API key prefix and expiration
`403`	Forbidden	Verify scope permissions and tenant access
`404`	Not Found	Confirm resource ID and endpoint path
`429`	Rate Limited	Implement backoff; review quota dashboard
`500`	Server Error	Transient; retry or contact support

🚫 Error Payload Structure

All errors follow this format for consistent handling:

json

{
  "error": {
    "code": "invalid_scope",
    "message": "API key lacks required 'threat:write' permission.",
    "request_id": "req_9x8c7v6b5n4",
    "docs_url": "https://docs.cybervault.io/errors/invalid_scope"
  }
}