Commands

Endpoint: /api/events/commands/

Execute and manage commands on remote servers.

List

List commands

Retrieve a paginated list of commands.

Request

GET /api/events/commands/

Query parameters

Parameter	Type	Description
`server`	UUID	Filter by server ID (exact)
`shell`	string	Filter by shell type (exact)
`requested_by`	integer	Filter by requesting user ID (exact)
`requested_by_isnull`	boolean	Filter commands with no requester
`is_scheduled`	boolean	`true` for future-scheduled, `false` for past/immediate
`search`	string	Search by server name, command line, or requester name
`ordering`	string	Sort field (default: `-scheduled_at`). Options: `added_at`, `scheduled_at`, `delivered_at`, `acked_at`, `handled_at`
`page`	integer	Page number
`page_size`	integer	Results per page (default: 15, max: 100)

Response

{
  "count": 85,
  "next": "https://your-workspace.us1.alpacon.io/api/events/commands/?page=2",
  "previous": null,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "shell": "system",
      "line": "df -h",
      "success": true,
      "result": "Filesystem  Size  Used Avail Use% Mounted on\n/dev/xvda1  20G  8.5G  11G  46% /",
      "status": {
        "text": "Success",
        "color": "success",
        "cancellable": false,
        "message": "Finished at 2024-01-15 10:30:45"
      },
      "response_delay": 0.125,
      "elapsed_time": 0.023,
      "added_at": "2024-01-15T10:30:44Z",
      "server": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
      "username": "ubuntu",
      "groupname": "alpacon",
      "requested_by": {
        "id": 1,
        "username": "admin",
        "email": "admin@example.com"
      },
      "scheduled_at": "2024-01-15T10:30:44Z"
    }
  ]
}

Example

curl "https://your-workspace.us1.alpacon.io/api/events/commands/?ordering=-scheduled_at&page_size=20" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""

Execute

Execute command

Execute a command on one or multiple servers. Provide either server (single) or servers (multiple), not both.

Request

POST /api/events/commands/

Request parameters

Field	Type	Required	Description
`server`	UUID	Yes*	Target server ID
`servers`	array[UUID]	Yes*	Target server IDs (write-only, creates one command per server)
`line`	string	Yes	Command to execute (max 512 chars)
`username`	string	No	OS user to run as (default: current user)
`groupname`	string	No	OS group to run as (default: `alpacon`)
`env`	object	No	Environment variables
`data`	string	No	Additional data for the command
`scheduled_at`	datetime	No	Scheduled execution time (default: immediate)
`run_after`	array[UUID]	No	Command IDs that must complete first

* Either server or servers is required, not both.

MFA is required when executing commands as the root user.

Request body

{
  "server": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
  "line": "df -h",
  "username": "ubuntu",
  "groupname": "alpacon",
  "env": {
    "CUSTOM_VAR": "value"
  }
}

Request body (multiple servers)

{
  "servers": [
    "7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
    "8f4985df-50bc-42e5-b827-32fcc6655111"
  ],
  "line": "apt update",
  "username": "root"
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "line": "df -h",
  "env": null,
  "data": null,
  "username": "ubuntu",
  "groupname": "alpacon",
  "added_at": "2024-01-15T10:30:44Z",
  "scheduled_at": "2024-01-15T10:30:44Z",
  "server": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
  "requested_by": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com"
  },
  "run_after": []
}

Example

curl -X POST "https://your-workspace.us1.alpacon.io/api/events/commands/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
  -H "Content-Type: application/json" \
  -d '{"server": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8", "line": "df -h", "username": "ubuntu"}'

Get

Get command

Retrieve full details and results for a specific command.

Request

GET /api/events/commands/{command_id}/

Path parameters

Parameter	Type	Required	Description
`command_id`	UUID	Yes	Command ID

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "shell": "system",
  "line": "df -h",
  "env": null,
  "data": null,
  "success": true,
  "result": "Filesystem  Size  Used Avail Use% Mounted on\n/dev/xvda1  20G  8.5G  11G  46% /",
  "status": {
    "text": "Success",
    "color": "success",
    "cancellable": false,
    "message": "Finished at 2024-01-15 10:30:45"
  },
  "response_delay": 0.125,
  "elapsed_time": 0.023,
  "added_at": "2024-01-15T10:30:44Z",
  "scheduled_at": "2024-01-15T10:30:44Z",
  "delivered_at": "2024-01-15T10:30:44.500Z",
  "acked_at": "2024-01-15T10:30:44.625Z",
  "handled_at": "2024-01-15T10:30:44.648Z",
  "server": {
    "id": "7e3984de-49ab-4cc6-bcdf-21fbd35858b8",
    "name": "web-server-01"
  },
  "requested_by": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com"
  }
}

Example

curl "https://your-workspace.us1.alpacon.io/api/events/commands/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""

Cancel

Cancel command

Cancel a pending command. Only commands that have not yet been delivered to the server (delivered_at is null) can be cancelled.

Request

DELETE /api/events/commands/{command_id}/

Path parameters

Parameter	Type	Required	Description
`command_id`	UUID	Yes	Command ID

Response

204 No Content

Example

curl -X DELETE "https://your-workspace.us1.alpacon.io/api/events/commands/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""

Command status lifecycle

Each command progresses through a series of timestamps:

Field	Description
`added_at`	Command created
`scheduled_at`	Scheduled execution time
`delivered_at`	Sent to the server
`acked_at`	Server acknowledged receipt and began execution
`handled_at`	Execution completed

The status object provides a human-readable summary with text, color, cancellable, and message fields.

Error responses

Status	Error code	Description
400	`INVALID_COMMAND`	Invalid command
403	`API_TOKEN_ACL_NOT_ALLOWED`	Command not allowed by token ACL
404	`COMMAND_NOT_FOUND`	Command not found
409	`EVENT_COMMAND_ALREADY_SENT`	Cannot cancel (already delivered to server)
503	`SERVER_NOT_CONNECTED`	Server is offline