Bans Endpoints

Manage and query IP bans across all servers.

List Bans

Get all bans with optional filtering.

GET /api/v1/bans

Query Parameters

Parameter	Type	Description
server_id	string	Filter by server UUID
jail	string	Filter by jail name
ip	string	Filter by IP address
country	string	Filter by country code (e.g., CN, RU)
from	string	Start date (ISO 8601)
to	string	End date (ISO 8601)
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 50, max: 100)

Response

Success (200):

{
  "bans": [
    {
      "id": 12345,
      "ip": "192.168.1.100",
      "jail": "sshd",
      "server": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "hostname": "web-server-01"
      },
      "country": "CN",
      "country_name": "China",
      "asn": "AS4134",
      "asn_org": "China Telecom",
      "log_lines": "Failed password for root from 192.168.1.100",
      "banned_at": "2024-01-15T10:30:00Z",
      "ban_duration": 3600,
      "reported_to_abuseipdb": true
    }
  ],
  "total": 1523,
  "page": 1,
  "limit": 50
}

Example

curl "https://bloqd.example.com/api/v1/bans?jail=sshd&country=CN&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Get Ban

Get a specific ban by ID.

GET /api/v1/bans/{banId}

Path Parameters

Parameter	Type	Description
banId	integer	Ban ID

Response

Success (200):

{
  "id": 12345,
  "ip": "192.168.1.100",
  "jail": "sshd",
  "server": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "hostname": "web-server-01"
  },
  "country": "CN",
  "country_name": "China",
  "city": "Beijing",
  "latitude": 39.9042,
  "longitude": 116.4074,
  "asn": "AS4134",
  "asn_org": "China Telecom",
  "log_lines": "Failed password for root from 192.168.1.100 port 22 ssh2\nFailed password for root from 192.168.1.100 port 22 ssh2",
  "banned_at": "2024-01-15T10:30:00Z",
  "ban_duration": 3600,
  "expires_at": "2024-01-15T11:30:00Z",
  "reported_to_abuseipdb": true,
  "abuseipdb_score": 85
}

---

Report Ban

Report a new ban (used by agent).

POST /api/v1/bans

Request Body

{
  "ip": "192.168.1.100",
  "jail": "sshd",
  "log_lines": "Failed password for root from 192.168.1.100 port 22 ssh2",
  "ban_duration": 3600
}

Response

Success (201):

{
  "id": 12345,
  "ip": "192.168.1.100",
  "jail": "sshd",
  "server_id": "550e8400-e29b-41d4-a716-446655440000",
  "country": "CN",
  "banned_at": "2024-01-15T10:30:00Z",
  "reported_to_abuseipdb": true
}

---

Manual Ban

Manually ban an IP on a server.

POST /api/v1/servers/{serverId}/bans

Path Parameters

Parameter	Type	Description
serverId	string	Server UUID

Request Body

{
  "ip": "192.168.1.100",
  "jail": "sshd",
  "duration": 86400,
  "reason": "Manual ban - suspicious activity"
}

Response

Success (201):

{
  "message": "Ban command queued",
  "command_id": "cmd-abc123"
}

---

Unban IP

Remove a ban from a server.

DELETE /api/v1/servers/{serverId}/bans/{ip}

Path Parameters

Parameter	Type	Description
serverId	string	Server UUID
ip	string	IP address to unban

Query Parameters

Parameter	Type	Description
jail	string	Jail name (optional, unbans from all if not specified)

Response

Success (200):

{
  "message": "Unban command queued",
  "command_id": "cmd-abc124"
}

---

Get Ban Statistics

Get aggregated ban statistics.

GET /api/v1/bans/stats

Query Parameters

Parameter	Type	Description
server_id	string	Filter by server UUID
period	string	day, week, month (default: day)

Response

Success (200):

{
  "total_bans": 5420,
  "unique_ips": 1823,
  "bans_by_jail": [
    { "jail": "sshd", "count": 3200 },
    { "jail": "nginx-botsearch", "count": 1500 },
    { "jail": "postfix-sasl", "count": 720 }
  ],
  "bans_by_country": [
    { "code": "CN", "name": "China", "count": 2150 },
    { "code": "RU", "name": "Russia", "count": 980 },
    { "code": "US", "name": "United States", "count": 450 }
  ],
  "bans_by_hour": [
    { "hour": 0, "count": 180 },
    { "hour": 1, "count": 165 }
  ],
  "bans_by_day": [
    { "date": "2024-01-15", "count": 247 },
    { "date": "2024-01-14", "count": 312 }
  ]
}

---

IP Lookup

Get information about an IP address.

GET /api/v1/bans/lookup/{ip}

Path Parameters

Parameter	Type	Description
ip	string	IP address to lookup

Response

Success (200):

{
  "ip": "192.168.1.100",
  "country": "CN",
  "country_name": "China",
  "city": "Beijing",
  "latitude": 39.9042,
  "longitude": 116.4074,
  "asn": "AS4134",
  "asn_org": "China Telecom",
  "is_whitelisted": false,
  "ban_history": [
    {
      "server": "web-server-01",
      "jail": "sshd",
      "banned_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total_bans": 5,
  "abuseipdb": {
    "score": 85,
    "reports": 150,
    "last_reported": "2024-01-15T09:00:00Z"
  }
}

---

Report to AbuseIPDB

Manually report an IP to AbuseIPDB.

POST /api/v1/bans/{banId}/report

Path Parameters

Parameter	Type	Description
banId	integer	Ban ID

Response

Success (200):

{
  "message": "Reported to AbuseIPDB",
  "abuseipdb_score": 85
}