Create action

Wire a script to a server event.

This endpoint requires the Unlimited plan.

POST/api/scripts/{script}/actions

Create an action

Creates an action. Ploi will queue an install of a systemd unit on every server in servers. The unit calls a signed Ploi webhook when the trigger fires, and Ploi queues the script for execution. Poll the list endpoint (or watch the per-server status field) to see install progress.

Required attributes

Name
trigger
Type
string
Description
Event that fires the script. Currently supported: server.booted, server.shutdown.
Name
servers
Type
array
Description
Array of server IDs that should react to this trigger.

Optional attributes

Name
delay_seconds
Type
integer
Description
How long to wait after the trigger fires before Ploi runs the script. Useful for giving a freshly-booted box more time to settle. 0 (no delay) up to 7200 (2 hours). Defaults to 0.

Request

POST

/api/scripts/{script}/actions

curl -X POST "https://ploi.io/api/scripts/{script}/actions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "trigger": "server.booted",
    "servers": [12, 18],
    "delay_seconds": 30
  }'

Response

{
  "data": {
    "id": 1,
    "script_id": 42,
    "trigger": "server.booted",
    "trigger_label": "Server has booted",
    "delay_seconds": 30,
    "is_paused": false,
    "last_triggered_at": null,
    "servers": [
      { "server_id": 12, "status": "pending", "installed_at": null, "last_error": null },
      { "server_id": 18, "status": "pending", "installed_at": null, "last_error": null }
    ],
    "created_at": "2026-05-13 09:00:00",
    "updated_at": "2026-05-13 09:00:00"
  }
}