Automation Server

• Get Started
  • Examples
• Schedule Server Actions
  • Server Schedules
  • Delayed Execution
  • Shortcuts Actions
• Webhook / API
  • Examples
• Control Your Server
  • Status Alerts
  • Pending Requests
  • Disable Server Actions
• Limitations And Quotas
  • Always Foreground
  • Sequential Execution
  • Timeouts
  • Long-Running Shortcuts
  • Daily Quotas

Get Started

The Pushcut Automation Server enables you to automatically run your shortcuts, without confirmation or user interaction. After setting up a dedicated iOS device as a server all your shortcuts and HomeKit scenes will be available as server actions, ready to execute at any time.

To get started, install Pushcut on your dedicated server device (iOS 14 or higher, internet connection required) and tap Automation Server > Start Server On This Device.

Once you have a server running, you can trigger your shortcuts or HomeKit scenes in a variety of ways:

• Schedules: Define time-of-day or periodic triggers using server schedules.
• Locations: Use background triggers on your "mobile" device to execute server actions when entering or leaving locations.
• Notifications: Trigger server actions from Pushcut notifications, even on your watch.
• Shortcuts: Use the Execute Server Action Shortcuts action.
• HomeKit: Call the webhook in the Get contents of URL action to trigger server actions from Home automations.
• Integrations: Execute server actions from online services like IFTTT and Zapier.
• Anywhere else: Use the Pushcut API to execute server actions from any DIY setup.

Unless scheduled with a delay, server actions are executed virtually instantly on the server device (see Limitations for details). To learn more about other Pushcut features, check out the main help page.

Examples

Here are a few brief examples of what you can create with the Automation Server:

Automatically run a shortcut when you arrive at a location
Setup a background action based on a geofence or an iBeacon and select a Server action.

Trigger a HomeKit scene from IFTTT
Create a new IFTTT applet and select any trigger you want. Use the Pushcut service as your 'that' action and select your scene.

Fetch the content of your Apple Notes into Zapier
Create a shortcut that fetches the content your note (Find Notes action) and use the Pushcut action 'Execute Shortcut' in Zapier. Make sure to select 'Wait For Response'. Return a dictionary in shortcuts to pass multiple values as a JSON object in the response.

Serve a dynamic website from a shortcut
If your shortcut returns html code as text it will be displayed as a website in any browser.

Execute an iOS shortcut from a HomeKit automation
Convert your HomeKit automation into a shortcut and use the Get Contents of URL action to run a 'real' shortcut on your iOS server.

Add to Apple Reminders from Make
Create a shortcut that adds a reminder (eg: with Toolbox Pro) and use the HTTP module in Make to send any data as input. You can pass JSON as input and read it as a dictionary in Shortcuts.

Schedule Server Actions

With a running Automation Server, you can schedule shortcuts and HomeKit scenes to be executed at a future time. Once scheduled, the execution will happen fully automatically, without any further user confirmation or interaction.

Server Schedules

Use the Automation Server > Schedules feature to define simple, repeating schedules. You can either select a specific time on certain days of the week (eg: 'On weekends at 9 PM'), or a repeating interval (eg: 'ever 5 minutes'). There is also a toggle to allow the action to be run automatiically when your server starts as well as on its regular schedule. Please note that interval-based schedules require the Server Extended package.

You can manage these server schedules from any device linked to your account. If you disable or remove a schedule, all future executions are immediately cancelled.

Schedule options include:

• At a specific time on certain days. E.g. at 9am every week day.
• At various intervals based on minutes, hours, or days. E.g. every 20 minutes, every 6 hours, or every 5 days.

If you want to set up multiple Server actions (such as from a folder in Shortcuts), try the Create Server Schedule Shortcuts Action.

Delayed Execution

By using the delay option you can dynamically schedule individual server requests to be executed at a specific time in the future (eg: Run 'Turn Off Lights' in 5 minutes). Simply add a delay parameter in the request to schedule the action instead of executing it immedately. You can see and cancel all scheduled requests under Pending Requests.

Please note that the Server Extended package is required to schedule delayed requests.

Shortcuts Actions

Use Execute Server Action to schedule a shortcut or scene to run on your Automation Server. You can pass in an input value and choose to run the action immedately or with a delay. Just like with with the API you can set an identifier to override or cancel (Cancel Server Action) a scheduled execution. You can also send Pushcut notifications from Shortcuts.

Webhook / API

To execute a server action send a plain HTTP POST (or GET) request to https://api.pushcut.io/[secret]/execute?shortcut=[shortcut-name] or https://api.pushcut.io/[secret]/execute?homekit=[homekit-scene]

You can conveniently copy these URLs by selecting an action in the Automation Server > Server Actions view. The execute URL uses the same secret as the notification webhook. If you prefer to use a clean URL with an API-Key in the header, use the Pushcut API.

In addition to shortcut or homekit, the following optional parameters are supported as either query parameters (e.g. ?input=Some%20Value) or in a JSON body (e.g. {"input": "Some Value"}):

Parameter	Description
delay	If set, schedules the request for automatic execution in the future. The value needs to be a string containing a number and a time unit (eg: 15s, 10m, 1h, …). The value must be between 5 seconds (5s) and 30 days (30d). See Scheduled Requests for further details. Example: /execute?shortcut=TurnOff&delay=1m.
input	Value that will be passed through as the shortcut's input (not used for HomeKit scenes). If you pass a JSON object as input, you can use Get Dictionary from Input in your shortcut to access all values.
identifier	Only relevant for scheduled requests in combination with delay. If set, it will replace any previously scheduled action with the same identifier. You can also cancel scheduled actions. Example: /execute?shortcut=TurnOff&delay=30s&identifier=AutoTurnOff.
timeout	Either the number of seconds the request will wait for the shortcut to finish, or 'nowait'. If the shortcut does not return a result within the timeout, the request will fail with a 504 Gateway Timeout error. However, the shortcut might still finish successfully. A 'nowait' request will immedately return 202 Accepted, even if the shortcut execution were to fail. See Timeouts for further details. Example: Use /execute?shortcut=LongRunning&timeout=nowait to execute a long-running shortcut where you do not care for the result.

Examples

Triggering a delayed shortcut with input text

This will trigger a shortcut 10 minutes in the future with input Hello World:

curl -X "POST" "https://api.pushcut.io/[secret]/execute?shortcut=Your%20Shortcut" \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
    "input": "Hello World",
    "delay": "10m"
}'

Waiting for response from shortcut with JSON body

This will trigger a shortcut with the input {"aValue":"aValue"} and wait up to 10 seconds for a result:

curl -X "POST" "https://api.pushcut.io/[secret]/execute?shortcut=Your%20Shortcut" \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
    "input": { 
      "aValue": "aValue"
    },
    "timeout": "10s"
}'

Control Your Server

If you open the Pushcut Automation Server view on any other device linked to your iCloud account, you can tap Monitor Requests to check the server's status and see a history of the latest requests. Tap on any request in the list to see details about its execution. You can review error messages of failed requests, or manually clear out stuck requests (eg: after a shortcut crashed).

If the list of your shortcuts is no longer up-to-date, you can tap Update Shortcuts at any time (on any device). This will refresh the list of available server actions.

There's also a Shortcuts action you can use to start, stop or restart your server.

Status Alerts

In the Server tab, you can set up Status Alerts to be informed when the connection to your server is lost or restored. You can specify which device(s) should be notified and which events (connection loss/restoration) should trigger this. There is an option to make these time sensitive which will break through a Focus Mode.

Pending Requests

To see a list of all server actions that are scheduled for future execution go to Automation Server > Pending requests.

There you can cancel their execution by swiping left on list item. Note that this is not possible for actions originating from a server schedule.

You can also cancel one off scheduled actions that you assigned an identifier to via a Webhook using https://api.pushcut.io/[secret]/cancelExecution?identifier=[my-identifier].

Disable Server Actions

If you want to ensure that certain shortcuts or HomeKit scenes are never executed automatically, turn off the Enable all actions switch in the Server Actions view.

You will then need to explicitly enable the individual actions that you want to allow for server execution. Attempting to execute a disabled action will result in a failed request. You can enable and disable server actions from any device at any time.

Limitations And Quotas

Always Foreground

For technical reasons the Pushcut Automation server can only process requests while in the foreground (ie: the Pushcut app must be visible on the screen). That is why the server is intended to run on a dedicated, always-on iOS device. Similarly, any shortcut that is executed must complete without user interaction to allow giving back control to Pushcut.

Sequential Execution

Server actions can only be processed in sequence, one after the other. As a consequence, if several requests are made in a short period of time they will be queued up. This could ultimately lead to timeouts, especially when several long-running shortcuts are queued. Keep your shortcuts as short as possible as a best practice. In any case, the Automation Server will fail any request that is older than 5 minutes.

Timeouts

By default, the web API will wait 10 seconds for the iOS device to produce a response. After this period the request will return with a timeout error, even though the shortcut might still be running as intended. Use the timeout parameter to extend this duration, or set the 'nowait' option.

The default timeout is 10 seconds, and the Server Extended package is required to set values higher than this. In any case, the maximum duration you can wait for is 45 seconds. These limitations do not apply to 'nowait' requests.

Server actions triggered by notifications or background actions always use 'nowait'. If a request is stuck (eg: because a shortcut crashed) you can manually cancel it from the request list.

Long-Running Shortcuts

Even with the 'nowait' option, shortcuts should generally not run longer than 60 seconds. After this time, the Pushcut back end will report the Automation Server as disconnected until it returns to the foreground again. This might disrupt the execution of requests that come in while disconnected. If possible, split your long-running shortcuts into several parts and use Execute Server Action to schedule continuations as needed.

Daily Quotas

The Automation Server has the following daily limits in place. Any request that goes beyond these quotas will fail.
Number of requests: 100
Data in inputs and results: 10 MB

These limits can be extended with the Automation Server Extended package. The extended limits are:
Number of requests: 5000
Data in inputs and results: 100 MB

Limits will reset every midnight in the timezone of the iOS device running the server.