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. For server.booted and server.shutdown, 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. The update triggers fire from Ploi itself, so their servers are installed right away.

Required attributes

Name
trigger
Type
string
Description
Event that fires the script. One of:
- server.booted: the server finished booting.
- server.shutdown: the server is shutting down gracefully.
- server.updates-finished: Ploi finished an update run on the server (the automatic updates schedule, "Run updates now" or fixing the updates insight).
- server.packages-upgraded: like server.updates-finished, but only when the run actually upgraded packages. Useful for pm2 update, or to reboot when /var/run/reboot-required exists (use shutdown -r +1 so the script run can finish first).
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"
  }
}