// API Reference

API Reference

Programmatic access to all threat.gg data via authenticated REST endpoints.

Base URL

https://threat.gg/api/v1

Authentication

All requests require a Bearer token in the Authorization header. Find your API key in your account settings.

Authorization: Bearer YOUR_API_KEY

GET /dashboard

Returns aggregated dashboard statistics including attack counts by protocol for the last 24 hours.

# Request
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://threat.gg/api/v1/dashboard

# Response
{
  "ssh_count": 45231,
  "http_count": 12847,
  "ftp_count": 3219,
  "elasticsearch_count": 891,
  "postgres_count": 2103,
  "mysql_count": 1547,
  "kubernetes_count": 423,
  "ldap_count": 672,
  "telnet_count": 8934,
  "smb_count": 1205
}

GET /attacks?type=ssh&page=1

List attacks filtered by protocol type. Paginated, 25 results per page.

Parameter	Type	Description
`type`	string	Protocol type: ssh, http, ftp, elasticsearch, postgres, mysql, kubernetes, ldap, telnet, smb
`page`	integer	Page number (default: 1)

# Request
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://threat.gg/api/v1/attacks?type=ssh&page=1"

# Response
[
  {
    "guid": "a1b2c3d4-...",
    "attack_type": "ssh",
    "source_ip": "203.0.113.42",
    "country": "CN",
    "created_at": "2026-03-09T12:34:56Z"
  }
]

GET /attacks/:guid

Get full details for a specific attack including commands or payloads.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://threat.gg/api/v1/attacks/a1b2c3d4-...

GET /attackers/:guid

Get attacker details including IP, geolocation, and attack history.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://threat.gg/api/v1/attackers/e5f6g7h8-...

GET /ip/:address

Look up an IP address to see its reputation and attack history across all protocols.

# Request
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://threat.gg/api/v1/ip/203.0.113.42

# Response
{
  "ip": "203.0.113.42",
  "country": "CN",
  "city": "Beijing",
  "attack_count": 147,
  "protocols": ["ssh", "telnet"],
  "first_seen": "2026-01-15T08:22:00Z",
  "last_seen": "2026-03-09T11:45:00Z"
}

GET /commands/ssh?page=1

Get the most frequently observed SSH commands across all honeypots.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://threat.gg/api/v1/commands/ssh?page=1"

GET /credentials/ssh?page=1

Get the most frequently used credential pairs (username/password) from SSH attacks.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://threat.gg/api/v1/credentials/ssh?page=1"

GET /malware

List malware samples captured by honeypots, including file hashes and metadata.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://threat.gg/api/v1/malware

// MCP Server

MCP Server

threat.gg provides an MCP (Model Context Protocol) server for AI tool integration. This lets tools like Claude query your threat data using natural language.

Endpoint

https://threat.gg/mcp

Authentication

The MCP server uses OAuth 2.1 for authentication. When connecting from an MCP client, the OAuth flow is handled automatically. The authorization endpoint is at /oauth/authorize and the token endpoint is at /oauth/token.

Available Tools

Tool	Description
`search_attacks`	Search attacks by type, IP, or date range
`lookup_ip`	Get IP reputation and attack history
`get_dashboard_stats`	Dashboard statistics overview
`get_top_credentials`	Most common credential pairs
`get_top_commands`	Most common SSH commands
`get_malware`	Captured malware samples
`get_attack_trends`	Attack volume trends over time
`bulk_ip_check`	Check multiple IPs at once