🛡️ Threats API
Programmatic access to CyberVault's real-time threat intelligence, analysis engine, and incident management pipeline. Query, analyze, and respond to threats across your infrastructure.
api.cybervault.io/v2Authentication
All requests to the Threats API require a valid API key passed in the Authorization header. Generate keys from your Dashboard → API Keys.
# HTTP Header
Authorization: Bearer cv_live_8xK9mP2vQ7nR4wL5jT6yU0zA
Content-Type: application/json
Endpoints
Retrieves a paginated list of recently detected threats across your monitored environment. Supports filtering by severity, type, and time range.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| severityrequired | string | Filter by severity: critical, high, medium, low |
| limit | integer | Max results per page (default: 25, max: 100) |
| offset | integer | Pagination offset (default: 0) |
| since | ISO 8601 | Filter threats detected after this timestamp |
Response 200 OK
{
"data": [
{
"id": "thr_8f4a2c9d1e",
"type": "ransomware_attempt",
"severity": "critical",
"timestamp": "2025-03-15T08:42:11Z",
"source_ip": "192.168.1.45",
"indicators": ["hash:md5:a1b2c3", "domain:evil-payload.net"],
"status": "mitigated"
}
],
"meta": {
"total": 142,
"limit": 25,
"offset": 0
}
}
Submit a file hash, IP address, URL, or raw payload for real-time threat analysis. Returns a threat score, classification, and recommended mitigation steps.
Request Body
{
"target": "203.0.113.42",
"target_type": "ip",
"context": {
"environment": "production",
"network_zone": "dmz"
}
}
Response 200 OK
{
"analysis_id": "anl_9x7c2m4p0q",
"threat_score": 92,
"classification": "command_and_control",
"confidence": 0.97,
"mitigation": {
"action": "block_immediately",
"rule_id": "waf_rule_884",
"scope": "global"
}
}
Manually update the lifecycle status of a detected threat. Use to mark false positives, acknowledge incidents, or close tickets.
⚠️ Permission Note
Updating status to closed or ignored requires threat:write scope. Standard analyst keys only have threat:read.
Error Handling
The API uses standard HTTP status codes. All errors return a JSON body with a unique code and human-readable message.
- 400Bad Request / Invalid Parameters
- 401Unauthorized / Invalid API Key
- 403Forbidden / Insufficient Permissions
- 404Resource Not Found
- 429Rate Limit Exceeded
- 500Internal Server Error
{
"error": {
"code": "rate_limit_exceeded",
"message": "Too many requests. Limit: 100 req/min",
"retry_after": 42
}
}
Rate Limiting
API requests are throttled per API key to ensure platform stability. Limits vary by subscription tier.
| Tier | Requests / Minute | Requests / Hour | Burst Allowance |
|---|---|---|---|
| Starter | 30 | 1,000 | ±10% |
| Professional | 100 | 5,000 | ±15% |
| Enterprise | 500 | 20,000 | Custom |
Rate limit headers are included in every response:X-RateLimit-Limit: 100 | X-RateLimit-Remaining: 84 | X-RateLimit-Reset: 1678886400