Servers Endpoints

Manage servers connected to Bloqd.

List Servers

Get all servers.

GET /api/v1/servers

Query Parameters

Parameter	Type	Description
status	string	Filter by status: online, offline, all
search	string	Search by hostname or IP
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 20, max: 100)

Response

Success (200):

{
  "servers": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "hostname": "web-server-01",
      "ip_address": "192.168.1.10",
      "status": "online",
      "os": "Ubuntu 22.04",
      "fail2ban_version": "0.11.2",
      "agent_version": "1.0.0",
      "total_bans": 1523,
      "active_jails": 5,
      "last_heartbeat": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 5,
  "page": 1,
  "limit": 20
}

Example

curl "https://bloqd.example.com/api/v1/servers?status=online" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Get Server

Get a specific server by ID.

GET /api/v1/servers/{serverId}

Path Parameters

Parameter	Type	Description
serverId	string	Server UUID

Response

Success (200):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "hostname": "web-server-01",
  "ip_address": "192.168.1.10",
  "status": "online",
  "os": "Ubuntu 22.04",
  "fail2ban_version": "0.11.2",
  "agent_version": "1.0.0",
  "total_bans": 1523,
  "bans_today": 47,
  "active_jails": 5,
  "jails": [
    {
      "name": "sshd",
      "enabled": true,
      "current_bans": 3
    }
  ],
  "metrics": {
    "cpu_percent": 25.5,
    "memory_percent": 60.2,
    "disk_percent": 45.0
  },
  "last_heartbeat": "2024-01-15T10:30:00Z",
  "created_at": "2024-01-01T00:00:00Z"
}

---

Create Server

Register a new server.

POST /api/v1/servers

Request Body

{
  "hostname": "new-server-01",
  "ip_address": "192.168.1.20",
  "description": "New web server"
}

Response

Success (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "hostname": "new-server-01",
  "ip_address": "192.168.1.20",
  "description": "New web server",
  "api_key": "f2b_newserverkey123...",
  "install_command": "curl -sSL https://bloqd.example.com/install | sudo bash -s -- --token=abc123",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z"
}

caution

The api_key is only shown once. Save it securely.

---

Update Server

Update server details.

PATCH /api/v1/servers/{serverId}

Path Parameters

Parameter	Type	Description
serverId	string	Server UUID

Request Body

{
  "hostname": "web-server-01-updated",
  "description": "Primary web server"
}

Response

Success (200):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "hostname": "web-server-01-updated",
  "description": "Primary web server",
  "updated_at": "2024-01-15T10:30:00Z"
}

---

Delete Server

Remove a server from Bloqd.

DELETE /api/v1/servers/{serverId}

Path Parameters

Parameter	Type	Description
serverId	string	Server UUID

Response

Success (200):

{
  "message": "Server deleted successfully"
}

---

Server Heartbeat

Agent heartbeat endpoint (used by agent).

POST /api/v1/servers/heartbeat

Request Body

{
  "hostname": "web-server-01",
  "os": "Ubuntu 22.04",
  "fail2ban_version": "0.11.2",
  "agent_version": "1.0.0",
  "metrics": {
    "cpu_percent": 25.5,
    "memory_percent": 60.2,
    "disk_percent": 45.0,
    "uptime": 864000
  },
  "jails": [
    {
      "name": "sshd",
      "enabled": true,
      "current_bans": 3
    }
  ]
}

Response

Success (200):

{
  "message": "Heartbeat received",
  "commands": []
}

---

Get Server Jails

Get all jails for a server.

GET /api/v1/servers/{serverId}/jails

Response

Success (200):

{
  "jails": [
    {
      "name": "sshd",
      "enabled": true,
      "current_bans": 3,
      "total_bans": 156,
      "filter": "sshd",
      "logpath": "/var/log/auth.log",
      "maxretry": 5,
      "bantime": 3600,
      "findtime": 600
    }
  ]
}

---

Get Server Stats

Get statistics for a server.

GET /api/v1/servers/{serverId}/stats

Query Parameters

Parameter	Type	Description
period	string	day, week, month (default: day)

Response

Success (200):

{
  "total_bans": 1523,
  "bans_period": 47,
  "unique_ips": 89,
  "top_jails": [
    { "name": "sshd", "count": 30 },
    { "name": "nginx-botsearch", "count": 12 }
  ],
  "top_countries": [
    { "code": "CN", "name": "China", "count": 25 },
    { "code": "RU", "name": "Russia", "count": 15 }
  ],
  "bans_by_hour": [
    { "hour": "00:00", "count": 5 },
    { "hour": "01:00", "count": 3 }
  ]
}

---

Regenerate Server Token

Generate a new installation token.

POST /api/v1/servers/{serverId}/regenerate-token

Response

Success (200):

{
  "install_command": "curl -sSL https://bloqd.example.com/install | sudo bash -s -- --token=newtoken123"
}