Commands Endpoints

Execute and manage remote commands on servers.

List Commands

Get command history.

GET /api/v1/commands

Query Parameters

Parameter	Type	Description
server_id	string	Filter by server UUID
status	string	Filter by status: pending, running, completed, failed, timeout
type	string	Filter by command type
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):

{
  "commands": [
    {
      "id": "cmd-abc123",
      "type": "ban-ip",
      "server": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "hostname": "web-server-01"
      },
      "params": {
        "jail": "sshd",
        "ip": "192.168.1.100"
      },
      "status": "completed",
      "result": {
        "success": true,
        "output": "IP 192.168.1.100 banned"
      },
      "initiated_by": "admin",
      "created_at": "2024-01-15T10:30:00Z",
      "completed_at": "2024-01-15T10:30:05Z"
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 50
}

---

Get Command

Get a specific command by ID.

GET /api/v1/commands/{commandId}

Path Parameters

Parameter	Type	Description
commandId	string	Command ID

Response

Success (200):

{
  "id": "cmd-abc123",
  "type": "ban-ip",
  "server": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "hostname": "web-server-01"
  },
  "params": {
    "jail": "sshd",
    "ip": "192.168.1.100"
  },
  "status": "completed",
  "result": {
    "success": true,
    "output": "IP 192.168.1.100 banned",
    "exit_code": 0
  },
  "initiated_by": "admin",
  "created_at": "2024-01-15T10:30:00Z",
  "started_at": "2024-01-15T10:30:02Z",
  "completed_at": "2024-01-15T10:30:05Z"
}

---

Execute Command

Execute a command on a server.

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

Path Parameters

Parameter	Type	Description
serverId	string	Server UUID

Request Body

{
  "type": "ban-ip",
  "params": {
    "jail": "sshd",
    "ip": "192.168.1.100"
  }
}

Available Command Types

Type	Description	Required Params
ban-ip	Ban an IP	jail, ip
unban-ip	Unban an IP	jail, ip
jail-status	Get jail status	jail
jail-enable	Enable a jail	jail
jail-disable	Disable a jail	jail
jail-reload	Reload jail config	jail
reload-all	Reload fail2ban	-
service-restart	Restart fail2ban	-
deploy-template	Deploy template	template_id, settings
remove-template	Remove template	template_name

Response

Success (201):

{
  "id": "cmd-abc123",
  "type": "ban-ip",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z"
}

Example

curl -X POST "https://bloqd.example.com/api/v1/servers/550e8400-e29b-41d4-a716-446655440000/commands" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ban-ip",
    "params": {
      "jail": "sshd",
      "ip": "192.168.1.100"
    }
  }'

---

Batch Execute

Execute the same command on multiple servers.

POST /api/v1/commands/batch

Request Body

{
  "server_ids": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ],
  "type": "reload-all"
}

Response

Success (201):

{
  "commands": [
    {
      "id": "cmd-abc123",
      "server_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "pending"
    },
    {
      "id": "cmd-abc124",
      "server_id": "550e8400-e29b-41d4-a716-446655440001",
      "status": "pending"
    }
  ]
}

---

Cancel Command

Cancel a pending command.

DELETE /api/v1/commands/{commandId}

Path Parameters

Parameter	Type	Description
commandId	string	Command ID

Response

Success (200):

{
  "message": "Command cancelled"
}

note

Only pending commands can be cancelled. Running commands will continue to completion.

---

Retry Command

Retry a failed or timed-out command.

POST /api/v1/commands/{commandId}/retry

Path Parameters

Parameter	Type	Description
commandId	string	Command ID

Response

Success (201):

{
  "id": "cmd-abc125",
  "type": "ban-ip",
  "status": "pending",
  "retry_of": "cmd-abc123",
  "created_at": "2024-01-15T10:35:00Z"
}

---

Get Pending Commands

Get pending commands for a server (used by agent).

GET /api/v1/servers/{serverId}/commands/pending

Response

Success (200):

{
  "commands": [
    {
      "id": "cmd-abc123",
      "type": "ban-ip",
      "params": {
        "jail": "sshd",
        "ip": "192.168.1.100"
      }
    }
  ]
}

---

Report Command Result

Report command execution result (used by agent).

POST /api/v1/commands/{commandId}/result

Path Parameters

Parameter	Type	Description
commandId	string	Command ID

Request Body

{
  "success": true,
  "output": "IP 192.168.1.100 banned successfully",
  "exit_code": 0
}

Response

Success (200):

{
  "message": "Result recorded"
}

---

Command Statistics

Get command execution statistics.

GET /api/v1/commands/stats

Query Parameters

Parameter	Type	Description
server_id	string	Filter by server UUID
period	string	day, week, month

Response

Success (200):

{
  "total": 1523,
  "by_status": {
    "completed": 1450,
    "failed": 50,
    "timeout": 23
  },
  "by_type": {
    "ban-ip": 800,
    "unban-ip": 300,
    "reload-all": 200,
    "deploy-template": 150,
    "other": 73
  },
  "avg_execution_time_ms": 2500,
  "success_rate": 95.2
}