---
title: "PUT /v2/custom-actions/{custom_action_id}/"
method: PUT
path: "/v2/custom-actions/{custom_action_id}/"
tags: ["blueprints_Custom Actions API"]
---

# PUT /v2/custom-actions/{custom_action_id}/

`PUT /v2/custom-actions/{custom_action_id}/`

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

Updates an existing custom action by ID, modifying any combination of its name, type, state, placement, properties, and options.
Accepts a CustomActionUpdate body where all fields are optional — only the fields provided will be updated. If options is included, it fully replaces the existing options list. Returns the updated CustomActionRead object on success. Returns 400 if the update is invalid (e.g., an invalid state transition) or 409 if the new name conflicts with an existing custom action.

**About Update Custom Action**

Custom action updates follow partial-update semantics for most fields, but options is a full replacement — supplying it overwrites all existing options and their associated scripts. State transitions follow lifecycle rules: only active custom actions can be deployed to Linux devices. Moving an action from active to inactive or draft will prevent it from being used in new Blueprint deployments.

**Key Fields**

custom_action_id — UUID of the custom action to update (path parameter, required)

name — Updated display name (1–50 characters; must remain unique within the tenant)

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

state — Updated lifecycle state: draft, active, or inactive; only active actions are deployable

position_in_blueprints — Updated Blueprint section placement

position_in_device_settings — Updated device Quick Actions placement

properties — Replacement object for description, info_message, and tooltip_message

options — Replacement list of options; each option requires label, key UUID, and scripts.linux with script and interpreter

**Common Use Cases**

Activate a draft custom action by updating state to active when it's ready for deployment

Update script content by supplying a new options array with revised scripts

Rename or reposition a custom action within Blueprint sections

**Best Practices**

Retrieve the current state of the action with GET /v2/custom-actions/{custom_action_id}/ before updating to avoid unintentional changes

When updating options, include all options you want to retain — the list is fully replaced, not merged

Validate state transitions: moving from active to inactive may affect Blueprints currently referencing this action

**Workflow**

Retrieve the current action with GET /v2/custom-actions/{custom_action_id}/

Build a CustomActionUpdate payload with only the fields you intend to change (or a full options replacement if updating scripts)

Submit PUT /v2/custom-actions/{custom_action_id}/

Confirm the response reflects the updated fields and review the new updated_at timestamp

## Path parameters

- `custom_action_id` string, uuid, required

## Request body

- BlueprintsCustomActionUpdate — Update a custom action. All fields are optional.
  - `name` string — Custom action name
  - `type` 'button' | 'toggle' | 'radio' | 'dropdown' — The UI component type for this custom action
  - `state` 'draft' | 'active' | 'inactive' — The current operational state of the custom action
  - `position_in_blueprints` 'none' | 'blueprints_apps_and_configuration' | 'blueprints_connectivity' | 'blueprints_device_security' | 'blueprints_display_and_branding' | 'blueprints_esper_settings' | 'blueprints_scripts' | 'blueprints_files' | 'blueprints_platform_services' | 'blueprints_hardware_settings' | 'blueprints_sound' | 'blueprints_system_updates' | 'blueprints_time_and_date' — The location in the blueprint where the custom action will be added
  - `position_in_device_settings` 'none' | 'device_quick_settings' — The location in the device's Quick Actions where the custom action will be added
  - `properties` object — Object for the description, info_message, and tooltip_message. Replaces the existing properties.
  - `options` BlueprintsOptionsRequest[] — A new list of options to replace the existing ones
    - `label` string, required — Label shown on the UI
    - `key` string, uuid, required — Unique key identifier for the option
    - `scripts` object, required — Platform-specific scripts. Currently only Linux platform is supported. Platform key must be lowercase "linux".
      - `linux` BlueprintsPlatformScriptRequest, required
        - `script` string, required — The script content to be executed on Linux devices
        - `interpreter` string, required — Interpreter used to run the script. Default is "bash" if not specified. Common values include "bash", "sh", "python", "python3"

## Response `200`

Success

- object
  - `content` BlueprintsCustomActionRead
    - `name` string, required — Custom Action name
    - `type` 'button' | 'toggle' | 'radio' | 'dropdown', required — The UI component type for this custom action
    - `state` 'draft' | 'active' | 'inactive', required — The current operational state of the custom action. Only active custom actions can be deployed to Linux devices.
    - `position_in_blueprints` 'none' | 'blueprints_apps_and_configuration' | 'blueprints_connectivity' | 'blueprints_device_security' | 'blueprints_display_and_branding' | 'blueprints_esper_settings' | 'blueprints_scripts' | 'blueprints_files' | 'blueprints_platform_services' | 'blueprints_hardware_settings' | 'blueprints_sound' | 'blueprints_system_updates' | 'blueprints_time_and_date', required — The location in the blueprint where the custom action will be added
    - `position_in_device_settings` 'none' | 'device_quick_settings', required — The location in the device's Quick Actions where the custom action will be added
    - `properties` object, required — Object for the description, info_message, and tooltip_message.
    - `id` string, uuid, required — Unique identifier for the custom action
    - `options` BlueprintsOptionsResponse[], required — List of options for the custom action
      - `label` string, required — Label shown on the UI
      - `key` string, uuid, required — Unique key identifier for the option
      - `scripts` object, required — Platform-specific script references. Currently only Linux platform is supported. Platform key must be lowercase "linux".
        - `linux` BlueprintsPlatformScriptResponse, required
          - `script_id` string, uuid, required — Script identifier stored in external storage
    - `created_at` string, date-time, required — When the custom action was created
    - `updated_at` string, date-time, required — When the custom action was last updated
    - `created_by` integer, required — User ID who created the custom action
    - `updated_by` integer, required — User ID who last updated the custom action
  - `message` string
  - `code` 200

## Other responses

- `400` — Bad Request (validation error or invalid state transition)
- `404` — Custom Action not found
- `409` — Conflict - Custom Action name already exists
- `500` — Internal Server Error

---

[API](https://skmtc.net/esper/apis/esper-api-reference.md) · [All operations](https://skmtc.net/esper/apis/esper-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/esper/esper-api-reference/revisions/e1f64cbb488e/schema)