Skip to main content

Perform Node Action

Performs a lifecycle, security, or rename action on a single node. The action is selected by the type field in the request body. Some actions require additional fields (see the type description below for the per-action contract).

All actions return the same response envelope - data.action_type echoes the action that was performed. Long-running actions (reinstall, save_images) return status: "done" immediately to indicate the request was accepted; the node will transition through the actual workflow asynchronously.

PUT/api/v1/nodes/{node_id}/actions/

Path parameters

  • node_idPathstringrequired

    Path parameter node_id.

Query parameters

  • project_idQuerystringoptional

    Identifier of the project to scope the request to. Optional; if omitted, the account's default project is used.

    • optional
    • if omitted, the request is applied to the default project
    example{{project_id}}
  • apikeyQuerystringoptional

    API key used to authenticate the request

    • required
    • must be a valid alphanumeric API key
    example{{api_key}}
  • locationQuerystringoptional

    Region identifier for the target node

    • required
    • non-empty string
    • must be a valid location identifier
    example{{location}}

Request body

application/json

object
typestringrequiredpower_off | power_on | reboot…

Discriminator that selects which action to perform. Most actions require no additional fields; the two exceptions are save_images and rename, both of which require the name field below.

Supported values and their semantics:

  • power_off - gracefully shut down the node.

  • power_on - boot a powered-off node.

  • reboot - reboot the node (soft reboot via the guest OS where possible).

  • reinstall - wipe the node and reinstall the same OS image. Destructive: all data on the root disk is lost.

  • save_images - capture the current root disk as a saved image template. Requires name.

  • rename - change the node's display name. Requires name.

  • enable_recovery_mode / disable_recovery_mode - toggle recovery-mode boot (mounts the root disk on a rescue image).

  • lock_vm / unlock_vm - administrative lock that blocks further actions until unlocked.

  • enable_accidental_protection / disable_accidental_protection - require an extra confirmation step before destructive actions.

  • enable_node_compliance / disable_node_compliance - toggle security-compliance mode (hardens the node per the platform's compliance baseline).

examplepower_off
  • required
  • must be one of the supported action identifiers above
namestring

Required when type is save_images (sets the name of the saved image template) or rename (sets the new node display name). Ignored for all other action types.

examplemy-saved-image
  • required when `type` is `save_images` or `rename`
  • non-empty string
  • max length 255 characters
  • no leading or trailing whitespace

Responses

200Successful response
object
codeinteger

HTTP status code. 200 indicates the action was accepted.

example200
  • integer between 100 and 599
dataobject
errorsobject
messagestring

Human-readable status message.

exampleSuccess
  • non-empty string
  • maximum length 255 characters