Commands

List

List commands

Retrieve a paginated list of commands.

Request

GET /api/events/commands/

Query parameters

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\""

Bulk status lookup

When tracking many commands at once (for example, a dashboard or automation polling for results), pass a comma-separated list of command IDs to id__in instead of issuing one GET /api/events/commands/{command_id}/ per command. Set page_size=100 as well: the default page size is 15, so without it a request for more than 15 IDs returns only the first page and a next link rather than every result.

curl "https://your-workspace.us1.alpacon.io/api/events/commands/?id__in=550e8400-e29b-41d4-a716-446655440000,9b52a7c4-13de-48f6-a01b-7f3e5d982c44&page_size=100" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""

Up to 100 IDs can be requested at once; exceeding this limit returns 400 with EVENT_COMMAND_BULK_LIMIT_EXCEEDED, and any value that is not a valid UUID returns 400. An empty id__in value is ignored: the request behaves as if the parameter were omitted and returns the full accessible list. Results follow the ordering parameter (default: -scheduled_at), not the order of the IDs in the request, so match each result to your list by its id field. IDs for commands you cannot access or that no longer exist are silently excluded; compare the response count with the number of unique IDs you requested to detect exclusions.

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

* 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

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

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\""