v2

HBV API v2 Documentation (Beta)

Enhanced & Experimental Endpoints

Overview

HBV API v2 introduces experimental features including webhooks, batch operations, GraphQL queries, and WebSocket streaming for real-time updates.

Beta Status: API v2 is in active development. Endpoints may change without notice. Use v1 for production deployments.

What's New in v2

Migration from v1

API v2 is backwards-compatible with v1 core endpoints. To migrate:

  1. Update base URL from /api/v1 to /api/v2
  2. Same authentication (API keys work across versions)
  3. Review new optional fields in request bodies
  4. Test webhook integrations in staging first
Recommended: Use v1 for stable operations, v2 for testing new features.

New Features

POST /api/v2/webhooks

Protected endpoint - Register webhook for event notifications

Request Body

{
  "url": "https://your-server.com/webhook",
  "event_types": ["beacon", "result", "agent_offline"],
  "secret": "your_webhook_secret"
}

Event Types

  • beacon - Agent check-in events
  • result - New results submitted
  • agent_offline - Agent goes inactive
  • high_severity - High/critical results detected

Webhook Payload Example

{
  "event": "result",
  "timestamp": "2025-12-19T12:00:00Z",
  "data": {
    "agent_id": "agent-001",
    "module": "port-scan",
    "severity": "high",
    "target": "example.com"
  },
  "signature": "sha256_hmac_signature"
}

POST /api/v2/results/batch

Protected endpoint - Submit multiple results in one request

Request Body

{
  "results": [
    {
      "agent_id": "agent-001",
      "module": "port-scan",
      "target": "example.com",
      "data": {"ports": [80, 443]}
    },
    {
      "agent_id": "agent-001",
      "module": "subdomain-enum",
      "target": "example.com",
      "data": {"subdomains": ["www", "api", "mail"]}
    }
  ]
}

Response Example

{
  "success": true,
  "processed": 2,
  "failed": 0,
  "ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ]
}

POST /api/v2/graphql

Protected endpoint - GraphQL query interface (experimental)

Query Example

query {
  agents(active: true) {
    agent_id
    hostname
    last_seen
    results(limit: 10) {
      module
      target
      timestamp
    }
  }
}

Response Example

{
  "data": {
    "agents": [
      {
        "agent_id": "agent-001",
        "hostname": "recon-box-01",
        "last_seen": "2025-12-19T12:00:00Z",
        "results": [
          {
            "module": "port-scan",
            "target": "example.com",
            "timestamp": "2025-12-19T11:00:00Z"
          }
        ]
      }
    ]
  }
}

WS /api/v2/stream

Protected endpoint - Real-time event streaming via WebSocket

Connection

const ws = new WebSocket('wss://your-api.local/api/v2/stream');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'auth',
    api_key: 'hbv_your_key'
  }));

  ws.send(JSON.stringify({
    type: 'subscribe',
    events: ['beacon', 'result']
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event received:', data);
};

Event Stream Example

{
  "type": "beacon",
  "agent_id": "agent-001",
  "timestamp": "2025-12-19T12:00:00Z"
}

{
  "type": "result",
  "agent_id": "agent-001",
  "module": "port-scan",
  "severity": "high"
}

Enhanced v1 Endpoints

All v1 endpoints are available in v2 with improvements:

GET /api/v2/results

Enhanced query capabilities with full-text search

New Query Parameters

  • search - Full-text search across data fields
  • sort - Sort by field (timestamp, severity, module)
  • order - Sort order (asc, desc)
  • fields - Comma-separated fields to return

Example

curl -H "X-API-Key: hbv_your_key" \
  "https://your-api.local/api/v2/results?search=port+80&sort=timestamp&order=desc"

Rate Limits

API v2 has increased rate limits:

Endpoint Type v1 Limit v2 Limit
Standard endpoints 100 req/min 200 req/min
Batch operations N/A 50 req/min
GraphQL N/A 100 queries/min
WebSocket N/A 10 connections/IP

Code Examples

Python Client (v2)

import requests

class HBVClientV2:
    def __init__(self, api_url, api_key):
        self.api_url = api_url
        self.headers = {'X-API-Key': api_key}

    def submit_batch(self, results):
        """Submit multiple results at once"""
        response = requests.post(
            f'{self.api_url}/api/v2/results/batch',
            headers=self.headers,
            json={'results': results}
        )
        return response.json()

    def register_webhook(self, url, event_types, secret):
        """Register webhook for notifications"""
        response = requests.post(
            f'{self.api_url}/api/v2/webhooks',
            headers=self.headers,
            json={
                'url': url,
                'event_types': event_types,
                'secret': secret
            }
        )
        return response.json()

# Usage
client = HBVClientV2('https://your-api.local', 'hbv_your_key')

# Batch submit
results = [
    {'agent_id': 'agent-001', 'module': 'port-scan', 'target': 'example.com', 'data': {'ports': [80, 443]}},
    {'agent_id': 'agent-001', 'module': 'dns-enum', 'target': 'example.com', 'data': {'records': []}}
]
client.submit_batch(results)

# Register webhook
client.register_webhook(
    'https://my-server.com/webhook',
    ['beacon', 'result'],
    'my_webhook_secret'
)

Roadmap

Planned features for future v2 releases:

Feedback Welcome: API v2 is shaped by community feedback. Report issues or suggest features on GitHub.

← Back to API Gateway

View API v1 Docs