⚠️ Linux only. Custom actions apply exclusively to Linux-managed devices. This endpoint is not applicable to Android, iOS, or Windows devices.

Creates a new custom action for the tenant.

Accepts a CustomActionCreate body defining the action's name, UI component type, lifecycle state, blueprint and device placement, display properties, and one or more options — each option containing a Linux platform script with its interpreter. Returns the created CustomActionRead object on success. Returns 409 if a custom action with the same name already exists.

About Create Custom Action

Custom actions are operator-defined interactive controls that execute scripts on Linux devices. When created, a custom action is placed in a specified section of a Blueprint V2 (via position_in_blueprints) and/or surfaced in the device's Quick Actions panel (via position_in_device_settings). Each option within the action maps a UI label to a script that runs on the device when the user triggers that option. Only active custom actions are eligible for deployment; new actions can be created in draft state for review before activation.

Key Fields

name — Unique display name for the custom action (1–50 characters; must be unique within the tenant)

type — UI component type: button, toggle, radio, or dropdown

state — Lifecycle state: draft, active, or inactive; only active actions can be deployed

position_in_blueprints — The Blueprint section where this action will appear (e.g., blueprints_scripts, blueprints_apps_and_configuration, or none)

position_in_device_settings — Device-side placement: device_quick_settings or none

properties — Object containing description, info_message, and tooltip_message for the UI

options — Array of option objects, each with a label, a unique key UUID, and a scripts.linux object containing script (the script content) and interpreter (e.g., bash, python3; defaults to bash)

Common Use Cases

Create a button-type action that runs a diagnostic script on Linux devices from the Blueprint settings

Define a toggle-type action that enables or disables a system feature via a shell script

Build a dropdown-type action with multiple options, each mapping to a different script

Best Practices

Create custom actions in draft state first; activate them only after validating the script logic

Ensure name is unique within the tenant — the API returns 409 on conflict

Provide meaningful label values in each option so device operators can identify which script they are triggering

Specify the interpreter explicitly (e.g., python3) rather than relying on the bash default when your script requires a different runtime

Workflow

Design your script content and identify which Blueprint section or Quick Actions position the action should occupy

Build the CustomActionCreate payload: set name, type, state: "draft", positions, properties, and options with embedded scripts

Submit POST /v2/custom-actions/

Capture the returned id and options[*].scripts.linux.script_id for future reference

When ready, update the action to state: "active" via PUT /v2/custom-actions/{custom_action_id}/ to make it deployable