Esper blueprints_Background Scripts API

openapi: 3.2.0
info:
  title: ESPER API REFERENCE blueprints_Background Scripts API
  x-logo:
    url: esper-logo-white.svg
    backgroundColor: '#141418'
    altText: Logo
  description: '# Introduction

    Welcome to Esper’s API documentation. The Esper API allows users to accomplish operations outside of the console. Some common uses for our APIs include observing device information and console activity, installing and updating apps, uploading files, and sending files to devices. Our users have also used the API to automate app updates, perform bulk actions, and more. Esper API endpoints use REST-based architecture and return JSON responses. See our documentation for:


    * Getting started guides

    * Commonly used API examples

    * API command examples

    * Automated Script examples

    * And more


    # Authentication


    You need to create an API Key to interact with our APIs. Learn more about generating an API Key. You can also learn more about Esper and sign up for an account at esper.io/signup. Some endpoints also require an Enterprise ID. This ID can be found in the API Management section of the Esper console. # Lifecycle Labels


    Esper uses lifecycle labels to communicate the support status of each API endpoint. Use the following table to understand what each label means and how to respond. Badge

    What it means

    Recommended action


    Stable

    This endpoint is fully supported and safe for production use. No action needed. Beta

    This endpoint is publicly available but may change. It is not recommended for production integrations. Use with caution. Monitor the API changelog for updates before relying on this endpoint. Legacy

    This endpoint uses an older architecture and is still supported, but a newer equivalent exists. It is not recommended for new integrations. Plan migration to the recommended replacement when possible. See the endpoint description for the alternative. Deprecated

    This endpoint has stopped being supported. A removal date may be added at a later time. A replacement is available or the feature is entirely retired. Migrate before the removal date listed in the endpoint description. Do not use this endpoint in new integrations. # Pagination


    Responses may be paginated. Use the following parameters to query the data. A full list of parameters can be found on the endpoint’s documentation page. Parameter

    Data Type

    Explanation


    limit

    integer

    Limit the data returned. Default = 20. offset

    integer

    Offset to the first item returned. Default = 0. ordering

    string

    Order the results set by the field name. Varies by endpoint. next

    string

    Paginate to the next response set. previous

    string

    Paginate to the last set response. # Errors

    We use standard HTTP status codes for success or failure. A typical error response may look something like this:


    ```json

    {

    "errors": [],

    "message": "error message",

    "status": 400

    }

    ```

    * `errors` - List of error details

    * `message` - Error description

    * `status` - HTTP status code


    Some common status codes and messages are:


    Number

    Message

    Explanation


    200

    OK

    The request succeeded. 201

    Resource creation

    A resource was created. 401

    Unauthorized

    The API key is invalid. 404

    Not found

    The resource was not found. 429

    Rate limit exceeded

    Too many requests. Wait a moment and try again. 500

    Server error

    Internal error. Wait a moment and try again. If the issue persists, contact Esper. See how our systems are doing by checking our status page. # Rate Limits

    To ensure quality of service for all customers, we enforce rate limits for API requests. Most customers won’t hit this limit with normal use. In case you experience 429 or rate limit exceeded errors, we recommend the following:

    * Try sending requests in batches. * Begin with about 20 requests at a time and building up from there. * Ensure your scripts are efficient and don’t contain redundant calls. * Reach out to your account manager to discuss your options.'
  termsOfService: https://esper.io/terms-of-service
  contact:
    email: developer@esper.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
  x-prefix-tag: esper cloud api
servers:
- url: https://{foo}-api.esper.cloud/api
  variables:
    foo:
      default: develop
      description: Custom end point
tags:
- name: blueprints_Background Scripts API
  description: APIs to manage background scripts. Background scripts are scripts that can be configured to run continuously or at specified intervals on devices.
  x-displayName: Background Scripts API
paths:
  /v2/background-scripts/:
    post:
      x-badges:
      - name: Stable
        color: green
      tags:
      - blueprints_Background Scripts API
      description: 'Creates a new background script for the tenant.


        Uploads a PowerShell script that Esper will execute on devices, depending on the always_run and frequency_in_mins fields.


        **About Background Scripts**

        Background Scripts let a tenant run custom automation directly on managed devices (currently Windows, via the powershell interpreter) outside of Esper''s built-in commands — for example, custom health checks, remediation logic, or integration with third-party tooling.


        **Key Fields / Query Parameters**

        - `script` — The script content to execute on devices

        - `interpreter` — Interpreter used to run the script — currently only powershell is supported

        - `always_run` — Whether the script runs continuously; when true, frequency_in_mins must be null

        - `frequency_in_mins` — Interval in minutes between executions; required when always_run is false

        - `timeout_in_mins` — Maximum runtime before the script is terminated; must be > 0, defaults to 60


        **Common Use Cases**

        - Running a custom health check or diagnostic script on a recurring schedule across a device fleet

        - Automating a remediation step that built-in commands don''t cover

        - Integrating with a third-party monitoring or compliance tool via a script


        **Best Practices**

        - Set an appropriate timeout_in_mins so a misbehaving script doesn''t run indefinitely on a device

        - Test a new script on a small blueprint/device scope before deploying broadly

        - Use always_run only for scripts genuinely meant to run continuously — otherwise set a frequency_in_mins to control execution cadence


        **Workflow**

        1. Write and test the PowerShell script content

        2. POST it to this endpoint with the desired always_run/frequency_in_mins/timeout_in_mins settings

        3. Reference the created background script from a Blueprint to deploy it to devices'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/blueprints_BackgroundScriptCreate'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    $ref: '#/components/schemas/blueprints_BackgroundScriptRead'
                  message:
                    type: string
                  code:
                    type: integer
                    enum:
                    - 201
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                  message:
                    type: string
                  code:
                    type: integer
                    enum:
                    - 400
        '409':
          description: Conflict - Background Script name already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: integer
                    enum:
                    - 409
      summary: Create background scripts
      x-summary-source: derived
      operationId: postV2BackgroundScripts
      x-operation-id-source: derived
    get:
      x-badges:
      - name: Stable
        color: green
      tags:
      - blueprints_Background Scripts API
      description: 'Retrieves all background scripts configured for the tenant.


        Returns the tenant''s background scripts with optional filtering by name and always_run, and standard pagination.


        **About Background Scripts**

        Background Scripts let a tenant run custom PowerShell automation on managed devices. This list endpoint is the primary way to review what scripts already exist before creating or reusing one.


        **Key Fields / Query Parameters**

        - `name` — Filter scripts by name

        - `always_run` — Filter to only continuously-running (or scheduled) scripts

        - `ordering` — Field to sort results by

        - `limit / offset` — Pagination controls


        **Common Use Cases**

        - Auditing all background scripts currently configured for the tenant

        - Finding an existing script to reuse or update rather than duplicating it

        - Reviewing which scripts are set to always_run versus scheduled


        **Best Practices**

        - Check this list before creating a new script to avoid duplicating existing automation

        - Filter by always_run when reviewing continuously-running scripts specifically, since these have the broadest device impact

        - Periodically review script content for scripts no longer in use


        **Workflow**

        1. GET this endpoint to review existing background scripts

        2. GET a specific script by ID to view its full content

        3. Create a new script via POST if none of the existing ones fit'
      parameters:
      - in: query
        name: ordering
        schema:
          type: string
        description: 'Order the results by a specific field (-field for descending order). Valid fields are ''name'', ''created_at'', ''updated_at'', ''created_by'', ''updated_by''.

          '
      - in: query
        name: name
        schema:
          type: string
        description: 'Filter the results by name (partial match, case insensitive).

          '
      - in: query
        name: always_run
        schema:
          type: boolean
        description: 'Filter the results by always_run flag.

          '
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        description: 'Number of results to return per page.

          '
      - in: query
        name: offset
        schema:
          type: integer
          minimum: 0
          default: 0
        description: 'The initial index from which to return the results.

          '
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: object
                    properties:
                      count:
                        type: integer
                        format: int64
                        description: The total number of background scripts
                      next:
                        type:
                        - string
                        - 'null'
                        description: The link to retrieve the next set of objects in the result set
                      previous:
                        type:
                        - string
                        - 'null'
                        description: The link to retrieve the previous set of objects in the result set
                      results:
                        type: array
                        items:
                          $ref: '#/components/schemas/blueprints_BackgroundScriptRead'
                  message:
                    type: string
                  code:
                    type: integer
      summary: Get background scripts
      x-summary-source: derived
      operationId: getV2BackgroundScripts
      x-operation-id-source: derived
  /v2/background-scripts/{background_script_id}/:
    get:
      x-badges:
      - name: Stable
        color: green
      tags:
      - blueprints_Background Scripts API
      description: 'Retrieves a single background script by ID, including its full content.


        Returns the background script''s metadata along with its full script content.


        **About Background Scripts**

        Background Scripts let a tenant run custom PowerShell automation on managed devices. This detail endpoint is the only way to retrieve the actual script content, as opposed to the list endpoint which returns metadata only.


        **Key Fields / Query Parameters**

        - `background_script_id` — ID of the background script to retrieve


        **Common Use Cases**

        - Reviewing a script''s full content before modifying or reusing it

        - Auditing exactly what code is running on devices via a specific background script

        - Confirming script content after an update to ensure it matches what was intended


        **Best Practices**

        - Use the list endpoint to find the background_script_id first, since it returns metadata only

        - Review full script content here before assigning it to additional Blueprints, especially for scripts you didn''t author

        - Treat script content as sensitive if it includes credentials or internal configuration


        **Workflow**

        1. List background scripts to find the target background_script_id

        2. GET this endpoint to retrieve full script content

        3. Assign the script to a Blueprint to deploy it to devices'
      parameters:
      - in: path
        name: background_script_id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    $ref: '#/components/schemas/blueprints_BackgroundScriptDetailRead'
                  message:
                    type: string
                  code:
                    type: integer
                    enum:
                    - 200
        '404':
          description: Background Script not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: integer
                    enum:
                    - 404
      summary: Get background scripts by background script id
      x-summary-source: derived
      operationId: getV2BackgroundScriptsByBackgroundScriptId
      x-operation-id-source: derived
components:
  schemas:
    blueprints_BackgroundScriptDetailRead:
      allOf:
      - $ref: '#/components/schemas/blueprints_BackgroundScriptRead'
      - type: object
        properties:
          script:
            type: string
            description: The script content fetched from S3
        required:
        - script
    blueprints_BackgroundScriptCreate:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 50
          description: Name of the background script
        script:
          type: string
          description: The script content to be executed on devices
        interpreter:
          type: string
          maxLength: 50
          default: powershell
          description: Interpreter used to run the script. Currently only 'powershell' is supported.
        always_run:
          type: boolean
          description: Whether the script runs continuously. When true, frequency_in_mins must be null.
        frequency_in_mins:
          type:
          - integer
          - 'null'
          description: Interval in minutes between script executions. Required when always_run is false, must be null when always_run is true.
        timeout_in_mins:
          type: integer
          minimum: 1
          default: 60
          description: Maximum runtime in minutes before the script is terminated. Must be > 0. Defaults to 60 if omitted.
        description:
          type:
          - string
          - 'null'
          maxLength: 300
          description: Optional description for the background script. Max 300 characters.
      required:
      - name
      - script
      - always_run
    blueprints_BackgroundScriptRead:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the background script
        name:
          type: string
          description: Name of the background script
        interpreter:
          type: string
          description: Interpreter used to run the script
        always_run:
          type: boolean
          description: Whether the script runs continuously
        frequency_in_mins:
          type:
          - integer
          - 'null'
          description: Interval in minutes between script executions
        timeout_in_mins:
          type: integer
          description: Maximum runtime in minutes before the script is terminated.
        description:
          type: string
          description: Description of the background script. Empty string if not set.
        created_at:
          type: string
          format: date-time
          description: When the background script was created
        updated_at:
          type: string
          format: date-time
          description: When the background script was last updated
        created_by:
          type: integer
          description: User ID who created the background script
        updated_by:
          type: integer
          description: User ID who last updated the background script
      required:
      - id
      - name
      - interpreter
      - always_run
      - timeout_in_mins
      - created_at
      - updated_at
      - created_by
      - updated_by
  securitySchemes:
    esper_cloud_api_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    pipelines_SCAPIAuthToken:
      type: http
      scheme: bearer
    device_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    apps_management_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    commands_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    drift_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    device_onboarding_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    tenant_apiKey:
      type: http
      scheme: bearer
      description: "#### API KEY - Access Token\nAccess token for API is passed as authorization header in calls. You need to generate this from your Esper Console at `<domain>-api.esper.cloud` where foo is the sub-domain name you gave for your Esper Dev environment when you signed up for your Esper account. Please follow the instructions [in this Help article](https://help.esper.io/hc/en-us/articles/12656959508497) to generate an access token.\nOnce you have the access token, you need to send an authorization header as below\n\n```bash\n\n    curl -X GET \\\n      https://<domain>-api.esper.cloud/api/enterprise/<enterprise_id>/device/ \\\n      -H 'Authorization: Bearer <ACCESS_TOKEN>' \\\n      -H 'Content-Type: application/json' \\\n```\n\n> Please note the use of keyword **Bearer** before the token value.\n\n\nYou can read more about api key authentication [here](https://help.esper.io/hc/en-us/articles/12656959508497).\n"
    foundation_AuthToken:
      type: apiKey
      in: header
      name: Authorization
    reports_bearerAuth:
      type: http
      scheme: bearer
    geofence_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-tagGroups:
- name: ESPER CLOUD API
  tags:
  - esper_cloud_api_Company Settings
  - esper_cloud_api_Application
  - esper_cloud_api_Application V1
  - esper_cloud_api_AndroidDevice
  - esper_cloud_api_Device Group
  - esper_cloud_api_Token (Deprecated)
  - esper_cloud_api_Commands V2
  - esper_cloud_api_Enterprise Policy
  - esper_cloud_api_Geofence
  - esper_cloud_api_Content
  - esper_cloud_api_User (Deprecated)
  - esper_cloud_api_User
  - esper_cloud_api_Blueprint (Deprecated)
  - esper_cloud_api_Directory Record
  - esper_cloud_api_Tile Icon
  - esper_cloud_api_Alerts
  - esper_cloud_api_Alarms
  - esper_cloud_api_Wallpapers
  - esper_cloud_api_Device Telemetry
  - esper_cloud_api_Daily and Custom Reports
  - esper_cloud_api_SSO Connections
  - esper_cloud_api_Roles
  - esper_cloud_api_Personal Access Token
- name: BLUEPRINTS
  tags:
  - blueprints_Blueprints API
  - blueprints_Custom Actions API
  - blueprints_Background Scripts API
- name: PIPELINES
  tags:
  - pipelines_System Status Code
  - pipelines_System
  - pipelines_Pipelines
  - pipelines_Stages
  - pipelines_Target Lists
  - pipelines_Targets
  - pipelines_Device Groups
  - pipelines_Operation Lists
  - pipelines_Operations
  - pipelines_Pipeline Runs
  - pipelines_Stage Runs
  - pipelines_Target Runs
- name: DEVICE
  tags:
  - device_Device
  - device_Device Heartbeat
  - device_Device Apps
  - device_Device Enrollment in EMM
  - device_Operations
  - device_DeviceOperations
  - device_MultiOS Remote Viewer
- name: APPS MANAGEMENT
  tags:
  - apps_management_VPP License Management
  - apps_management_VPP App Management
  - apps_management_Tenant Apps
  - apps_management_Apple App Store
  - apps_management_App List
  - apps_management_Webclips
  - apps_management_Provisioning Profiles
  - apps_management_Preferred Regions
  - apps_management_OEM Config Schema
  - apps_management_Esper Apps
  - apps_management_Tenant Esper Apps
- name: COMMANDS
  tags:
  - commands_Command Request
  - commands_Command Status
- name: DRIFT
  tags:
  - drift_Converge
  - drift_Converge Command
  - drift_Blueprint Drift
- name: DEVICE ONBOARDING
  tags:
  - device_onboarding_DEP Sync Request
  - device_onboarding_ABM Provisioning
- name: TENANT
  tags:
  - tenant_APNs certificate
  - tenant_DEP Profile
  - tenant_DEP Tokens
  - tenant_VPP Token Management
  - tenant_Google Enterprise
  - tenant_MDM Service Config
- name: FOUNDATION
  tags:
  - foundation_FoundryBuilds
  - foundation_FoundryDeviceModels
  - foundation_FoundryEvents
- name: REPORTS
  tags:
  - reports_Reports API
- name: GEOFENCE
  tags:
  - geofence_Geofences
  - geofence_Device State
x-provenance:
  method: harvested
  publisher: Esper
  source: https://api.esper.io/_bundle/openapi.json?download
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)