Skip to content

/v2/background-scripts/
Stable

Request

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
Bodyapplication/jsonrequired
namestring, [ 1 .. 50 ] charactersrequired

Name of the background script

scriptstringrequired

The script content to be executed on devices

interpreterstring, <= 50 characters

Interpreter used to run the script. Currently only 'powershell' is supported.

Default:"powershell"
always_runbooleanrequired

Whether the script runs continuously. When true, frequency_in_mins must be null.

frequency_in_minsinteger or null

Interval in minutes between script executions. Required when always_run is false, must be null when always_run is true.

timeout_in_minsinteger, >= 1

Maximum runtime in minutes before the script is terminated. Must be > 0. Defaults to 60 if omitted.

Default:60
descriptionstring or null, <= 300 characters

Optional description for the background script. Max 300 characters.

cURL
curl -i -X POST \
  https://develop-api.esper.io/_mock/openapi/v2/background-scripts/ \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "script": "string",
    "interpreter": "powershell",
    "always_run": true,
    "frequency_in_mins": 0,
    "timeout_in_mins": 60,
    "description": "string"
  }'

Responses

Success

Bodyapplication/json
contentobject(blueprints_BackgroundScriptRead)
messagestring
codeinteger
Value:201
Response
{
  "content": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "interpreter": "string",
    "always_run": true,
    "frequency_in_mins": 0,
    "timeout_in_mins": 0,
    "description": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "created_by": 0,
    "updated_by": 0
  },
  "message": "string",
  "code": 201
}