How to Create a Worklet through API?

How do I create a Worklet through the Automox API?

Worklets are created through the same endpoint as other policies. The distinguishing field is policy_type_name, which must be set to custom. The accepted values are patch, required_software and custom, where custom means Worklet.

For the current request and response reference, see the Automox Developer documentation.

Before you start

• You need an API key with permission to manage policies in the target organization.
• You need the organization ID. It is passed both as the o query parameter and as organization_id in the body, and the two must match.

A minimal Worklet

Start with the smallest payload that works, then add fields as you need them. This creates an unscheduled Windows Worklet:

curl -X POST 'https://console.automox.com/api/policies?o=ORG_ID' \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "name": "Example Worklet",
    "policy_type_name": "custom",
    "organization_id": ORG_ID,
    "configuration": {
      "os_family": "Windows",
      "evaluation_code": "exit 2",
      "remediation_code": "Write-Output \"remediation ran\"",
      "auto_reboot": false,
      "notify_reboot_user": false
    },
    "server_groups": []
  }'

Set os_family to the platform the Worklet targets, and write the code for that platform. A Worklet created with os_family of Windows runs PowerShell; one created for Mac or Linux runs shell script. Mixing them is a common cause of a Worklet that creates successfully and then fails on every device.

Scheduling fields

The schedule is expressed as integers rather than as names, which is the part most people get stuck on:

• schedule_days
• schedule_weeks_of_month
• schedule_months
• schedule_time, in HH:MM

Rather than deriving these by hand, the reliable approach is to build the schedule you want once in the console, then read it back through the API and copy the values:

curl -s 'https://console.automox.com/api/policies?o=ORG_ID' \
  -H 'Authorization: Bearer API_KEY'

Find your policy in the response and reuse its schedule_days, schedule_weeks_of_month, schedule_months and schedule_time values in the policies you create programmatically. This is faster than working out the encoding and it guarantees the schedule matches what the console produces.

Omit the schedule fields entirely to create an unscheduled Worklet that you run on demand.

Optional configuration

The configuration object accepts many more fields, including device targeting filters and custom user notification messages. Add only what you need. Fields belonging to patch policies, such as patch rules and optional-update handling, are not relevant to a Worklet and adding them makes the payload harder to troubleshoot.

Device targeting is set with device_filters_enabled and a device_filters array, for example:

"device_filters_enabled": true,
"device_filters": [
  { "field": "tag", "op": "in", "value": ["Windows", "Win10"] }
]

To assign the Worklet to groups instead, populate server_groups with the group IDs.

Confirming the result

The response contains the new policy, including its id. Confirm the Worklet appears in the console under Policies, and check that the evaluation and remediation code arrived intact. Code submitted through JSON has to be escaped correctly, so newlines and quotation marks are worth verifying before the policy runs anywhere.

Test on a single device or a small group before assigning it broadly.