---
title: "GET /v2/custom-actions/"
method: GET
path: "/v2/custom-actions/"
tags: ["blueprints_Custom Actions API"]
---

# GET /v2/custom-actions/

`GET /v2/custom-actions/`

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

Retrieves all custom actions defined for the tenant.
Returns a list of CustomActionRead objects representing every custom action in the tenant, including their name, type, state, position settings, options, and audit metadata. Supports ordering to control the sort order of results. Use this endpoint to enumerate available custom actions before assigning them to a Blueprint or deploying them to Linux devices.

**About Custom Actions**

Custom actions allow operators to define custom scripts and commands that can be surfaced on Linux devices, either within a Blueprint's settings sections or as device Quick Actions. Each custom action has a type (button, toggle, radio, or dropdown), a state (draft, active, or inactive), and one or more options, each of which contains a Linux platform script. Only active custom actions can be deployed to devices. Custom actions are managed separately from blueprints but referenced within Blueprint settings via position_in_blueprints.

**Key Query Parameters**

ordering — Sort results by a specified field; prefix with - for descending order (e.g., -created_at for newest first)

**Common Use Cases**

List all custom actions before deciding which to include in a Blueprint V2 configuration

Audit the state of all custom actions to identify which are active vs. draft or inactive

Retrieve id values for use in subsequent GET, PUT, or DELETE calls on specific custom actions

**Best Practices**

Filter mentally by state in your integration logic: only active custom actions can be deployed to devices; drafts are not eligible

Use ordering=-created_at to surface recently created or modified actions first

Pair with GET /v2/custom-actions/{custom_action_id}/ when you need the full option and script payload for a specific action

**Workflow**

Call GET /v2/custom-actions/ to retrieve the full list of tenant custom actions

Review the state and position_in_blueprints fields to identify which actions are deployment-ready

Use the returned id values to fetch, update, or delete individual custom actions as needed

## Query parameters

- `ordering` string
- `name` string
- `type` string
- `state` string
- `position_in_blueprints` string
- `position_in_device_settings` string
- `created_by` integer
- `updated_by` integer
- `limit` integer
- `offset` integer

## Response `200`

Success

- object
  - `content` object
    - `count` integer — The total number of custom actions
    - `next` string, nullable — The link to retrieve the next set of objects in the result set
    - `previous` string, nullable — The link to retrieve the previous set of objects in the result set
    - `results` 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` integer

## Other responses

- `400` — Bad Request

---

[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)