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