Me on Mastodon UpdateKit on Mastodon
UpdateKit API Docs
About the UpdateKit API
API Details
Use Cases
API Versions
Available Endpoints
Checking for Updates
Checking for Updates in Bulk
Getting Missed Update History
Getting Gallery Download URLs
Getting Shortcut Icons and Names
Distributing Pre-Release Versions
Skipping a Version
Specifying an iOS or Mac Version
UpdateKit API Response
UpdateKit Data Format
Best Practices for Gallery Sites
UpdateKit API
About the UpdateKit API
icon
The UpdateKit API provides makers of iOS Shortcuts and shortcut updaters with access to the powerful UpdateKit Engine that was used in the legacy UpdateKit shortcut. The API represents a shift away from the concept of standalone "updater" shortcuts and the future of shortcut updaters in general, with powerful logic running in the cloud to enable advanced functionality at lightning-fast speeds.
Easy to use. Integrating the UpdateKit API into your shortcut or updater is easy. You make a single API call and get back all of the information you need to present an update to your user if one is available. Best of all, your users don't have to add another shortcut to their library -- everything is handled directly within your shortcut using built-in actions, so you always know your user has access to the update mechanism. No more checking the user's shortcut list to see if they have a particular updater installed!
Incredibly powerful. The API provides an all-in-one solution for fetching the latest version of a shortcut from a variety of sources and comparing the version numbers to determine if your user's version is outdated. The UpdateKit API provides what is almost certainly the most comprehensive version number comparison algorithm of any shortcut updater. It is nearly 100% compliant with Semantic Versioning 2.0.0 (one small caveat applies to pre-release updates, see documentation below for more information) and supports extended version numbers that are not SemVer-compliant. It even supports advanced features like version-skipping and optional pre-release/beta versions.
Designed for convenience. Integrating with the UpdateKit API allows you to offload the vast majority of the update-checking logic from your updater, enabling you to focus on other features like UI presentation. Depending on the complexity of your remote data fetching and version number comparision systems, you could potentially remove dozens of actions or more from your shortcut. A single Get Contents of URL action can fetch data from the shortcut hosting service of your choice, perform version comparison (including support for skipping a version) and determine if an update is available in a split second.
API Details
Version Compare Tests
The tests below are run each time code is committed or deployed to the UpdateKit API.
In each test, the installed value represents the version currently installed on the user's device, available represents the version listed as the latest version on the remote server, and the update boolean shows whether an update should be expected given those version numbers. Other parameters, such as prerelease, are also considered on some tests.
[
  {
    "installed": "1.0",
    "available": "1.0",
    "update": false
  },
  {
    "installed": "1.0",
    "available": "1.0.1",
    "update": true
  },
  {
    "installed": "1.0.1",
    "available": "1.0",
    "update": false
  },
  {
    "installed": "1.0.0-beta.1",
    "available": "1.0.0",
    "update": true
  },
  {
    "installed": "1.0.0",
    "available": "1.0.0-beta.1",
    "update": false
  },
  {
    "installed": "1.0.1.0.1.0",
    "available": "1.0.1.0.0.1",
    "update": false
  },
  {
    "installed": "1.0.1.0.0.0",
    "available": "1.0.1.0.1.1",
    "update": true
  },
  {
    "installed": "2.0",
    "available": "1.0.1.0.0.1",
    "update": false
  },
  {
    "installed": "1.0.1.0.1.0",
    "available": "2",
    "update": true
  },
  {
    "installed": "1.0.1.0.1.0",
    "available": "2.0.0.0.1",
    "update": true
  },
  {
    "installed": "2",
    "available": "2.0",
    "update": false
  },
  {
    "installed": "3",
    "available": "2.0",
    "update": false
  },
  {
    "installed": "2.0",
    "available": "3",
    "update": true
  },
  {
    "installed": "1.0.10",
    "available": "1.0.1",
    "update": false
  },
  {
    "installed": "1.0.1",
    "available": "1.0.10",
    "update": true
  },
  {
    "installed": "1.0.1",
    "available": "1.0.01",
    "update": false
  },
  {
    "installed": "1.0.01",
    "available": "1.0.001",
    "update": false
  },
  {
    "installed": "1.0.001",
    "available": "1.0.01",
    "update": true
  },
  {
    "installed": "1.0.1",
    "available": "1.0.001",
    "update": false
  },
  {
    "installed": "1.0.001",
    "available": "1.0.1",
    "update": true
  },
  {
    "installed": "1.0.01",
    "available": "1.0.1",
    "update": true
  },
  {
    "installed": "1.0.10",
    "available": "1.0.01",
    "update": false
  },
  {
    "installed": "1.0-beta.10",
    "available": "1.0-beta.01",
    "update": false,
    "prerelease": true
  },
  {
    "installed": "1.0-beta.1",
    "available": "1.0-beta.01",
    "update": false,
    "prerelease": true
  },
  {
    "installed": "1.0-beta.01",
    "available": "1.0-beta.1",
    "update": true,
    "prerelease": true
  },
  {
    "installed": "1.0-beta.1",
    "available": "1.0-beta.001",
    "update": false,
    "prerelease": true
  },
  {
    "installed": "1.0-beta.0001",
    "available": "1.0-beta.1",
    "update": true,
    "prerelease": true
  },
  {
    "installed": "1.0.2",
    "available": "1.0.10",
    "update": true
  },
  {
    "installed": "1.0",
    "available": "2.0-alpha.1",
    "prerelease": false,
    "update": false
  },
  {
    "installed": "1.0",
    "available": "2.0-alpha.1",
    "prerelease": true,
    "update": true
  },
  {
    "installed": "2.0",
    "available": "1.0-beta.1",
    "prerelease": true,
    "update": false
  },
  {
    "installed": "1",
    "available": "1.0-beta.1",
    "prerelease": true,
    "update": false
  },
  {
    "installed": "2",
    "available": "1.0-beta.1",
    "prerelease": true,
    "update": false
  },
  {
    "installed": "1",
    "available": "2.0-beta.1",
    "prerelease": false,
    "update": false
  },
  {
    "installed": "1",
    "available": "2.0-beta.1",
    "prerelease": true,
    "update": true
  },
  {
    "installed": "2.0-a1",
    "available": "2.0-a2",
    "prerelease": false,
    "update": false
  },
  {
    "installed": "2.0-a1",
    "available": "2.0-a2",
    "prerelease": true,
    "update": true
  },
  {
    "installed": "2.0-a1",
    "available": "3.0-a2",
    "prerelease": true,
    "update": true
  },
  {
    "installed": "2.0-b1",
    "available": "3.0-a2",
    "prerelease": true,
    "update": true
  },
  {
    "installed": "2.0-b1",
    "available": "2.0-a2",
    "prerelease": true,
    "update": false
  },
  {
    "installed": "2.0-a1",
    "available": "2.0-b2",
    "prerelease": true,
    "update": true
  },
  {
    "installed": "2.0-alpha.1",
    "available": "2.0-beta.2",
    "prerelease": true,
    "update": true
  },
  {
    "installed": "2.0-a.20.1",
    "available": "2.0-alpha.20.1",
    "prerelease": true,
    "update": false
  },
  {
    "installed": "2.0-prerelease.20.1",
    "available": "2.0-test.20.1",
    "prerelease": true,
    "tags": [
      [
        "prerelease",
        "test"
      ],
      "rc"
    ],
    "update": false
  },
  {
    "installed": "2.0-prerelease.20.1",
    "available": "2.0-test.20.2",
    "prerelease": true,
    "tags": [
      [
        "prerelease",
        "test"
      ],
      "rc"
    ],
    "update": true
  },
  {
    "installed": "2.0-prerelease.20.1",
    "available": "2.0-rc.20.1",
    "prerelease": true,
    "tags": [
      [
        "prerelease",
        "test"
      ],
      "rc"
    ],
    "update": true
  },
  {
    "installed": "2.0-alpha.20.1",
    "available": "2.0-beta.20.1",
    "prerelease": true,
    "tags": [
      [
        "prerelease",
        "test"
      ],
      "rc"
    ],
    "update": false
  },
  {
    "installed": "2.0-alpha.20.1",
    "available": "2.0-beta.20.2",
    "prerelease": true,
    "tags": [
      [
        "prerelease",
        "test"
      ],
      "rc"
    ],
    "update": true
  },
  {
    "installed": "2.0-alpha.20.2",
    "available": "2.0-beta.20.1",
    "prerelease": true,
    "tags": [
      [
        "prerelease",
        "test"
      ],
      "rc"
    ],
    "update": false
  },
  {
    "installed": "2.0-rc.20.1",
    "available": "2.0-test.20.1",
    "prerelease": true,
    "tags": [
      [
        "prerelease",
        "test"
      ],
      "rc"
    ],
    "update": false
  },
  {
    "installed": "2.0-beta.20.1",
    "available": "2.0-beta.20.1",
    "prerelease": true,
    "update": false
  },
  {
    "installed": "2.0-beta.20.1",
    "available": "2.0-beta.20.2",
    "prerelease": true,
    "update": true
  },
  {
    "installed": "2.0-beta.20.2",
    "available": "2.0-beta.20.1",
    "prerelease": true,
    "update": false
  },
  {
    "installed": "2.0-dev1",
    "available": "2.0-test2",
    "prerelease": true,
    "tags": [
      "dev",
      "pre",
      "test"
    ],
    "update": true
  },
  {
    "installed": "2.0-test1",
    "available": "2.0-dev3",
    "prerelease": true,
    "tags": [
      "dev",
      "pre",
      "test"
    ],
    "update": false
  },
  {
    "installed": "2.0-test1",
    "available": "2.0-dev3",
    "prerelease": false,
    "tags": [
      "dev",
      "pre",
      "test"
    ],
    "update": false
  },
  {
    "installed": "2.0-test1",
    "available": "3.0-dev3",
    "prerelease": true,
    "tags": [
      "dev",
      "pre",
      "test"
    ],
    "update": true
  },
  {
    "installed": "3.0-dev1",
    "available": "2.0-test3",
    "prerelease": true,
    "tags": [
      "dev",
      "pre",
      "test"
    ],
    "update": false
  },
  {
    "installed": "1.0.0-alpha+build4",
    "available": "1.0.0-alpha+build5",
    "prerelease": true,
    "update": false
  },
  {
    "installed": "1.0.0-0.3.7",
    "available": "1.0.0-0.3.8",
    "prerelease": true,
    "update": true
  },
  {
    "installed": "1.0.0-0.3.8",
    "available": "1.0.0-0.3.7",
    "prerelease": true,
    "update": false
  },
  {
    "installed": "1.0.0-0.3.7",
    "available": "1.0.0",
    "prerelease": true,
    "update": true
  },
  {
    "installed": "1.0.0",
    "available": "1.0.0-0.3.7",
    "prerelease": true,
    "update": false
  },
  {
    "installed": "1.0.0",
    "available": "1.0.2",
    "prerelease": true,
    "skip": "1.0.2",
    "update": false
  },
  {
    "installed": "1.0.0",
    "available": "1.0.2",
    "prerelease": true,
    "skip": "1.0.1",
    "update": true
  },
  {
    "installed": "1.0.0",
    "available": "1.0.2",
    "prerelease": true,
    "skip": "1.0.3",
    "update": true
  },
  {
    "installed": "1.0",
    "available": "1.0.12-alpha1",
    "prerelease": true,
    "update": true
  },
  {
    "available": "1.0",
    "update": true
  }
]
The UpdateKit API was last deployed at 8:47:43 PM on 10/16/2025. The build version is v139.
A total of 68 version comparison engine tests passed during the build.
Modules provide support for specific gallery websites. These are supported in addition to generic URL support as outlined in the UpdateKit API documentation. More modules may be added over time as needed. A list of available modules is below.
Module statuses on this page are checked in real time, but do not guarantee that the gallery website is functioning as expected in all cases. Some gallery sites may experience intermittent issues that are not evident from the statuses below. It is up to the gallery sites to fix these issues when they occur.
Switchblade
URL: GitHub
Module Key: switchblade
Switchblade is a free self-hosted platform that you can use to distribute your shortcuts. You can learn more on GitHub.
RoutineHub
Module Key: routinehub
Status: RoutineHub appears to be online
ShareShortcuts
Module Key: shareshortcuts
Status: ShareShortcuts appears to be online
Use Cases
There are two potential use cases for the UpdateKit API: standalone shortcut updaters like UpdateKit, and direct integrations that require no shortcut updater at all.
For standalone updater shortcuts, the API provides all of the heavy lifting of fetching version data from the appropriate gallery site, computing version number comparision, and determining if an update should be presented to the user. Updater shortcuts can then build their UI on top of this, introducing additional functionality like the option to skip a version forever, along with their own iconography, text strings, and more.
However, thanks to the simplicity of the UpdateKit API, integrating it directly into a shortcut is feasible for any shortcut maker. There is no need to check and make sure the user has a specific updater installed before attempting to run it, and no fidgeting with hacky solutions like embedded updaters that modify Apple's shortcut files directly (which is essentially impossible with iOS 15's new shortcut verification functionality). Instead, in just a few actions, shortcut makers can have the UpdateKit API fetch all of the necessary update information for them, add their own update menu in under 20 actions (for a simple menu), and get on with the work of making their shortcut. Shortcut makers who want more advanced options without having to build them can gain the benefits of the UpdateKit API by integrating with an updater shortcut that supports it. An example of this type of integration is provided via the "Example" button at the top of the page.
API Versions
The UpdateKit API uses a versioned endpoint that will be incremented if breaking changes are deployed. You can continue using the previous version if you do not see a need to upgrade to the newer version.
Breaking changes are defined as any change that would cause existing implementations of the API to stop working as expected. This does not mean every change will result in a new version. For example, bug fixes will be applied to the same version so that users on that version can benefit without having to update their integrations.
Additionally, new features may be added to a version as long as they do not interfere with existing functionality. For example, if a new optional field is supported in the POST body, or if new values are returned with the API response, those changes would not be considered breaking. However, if the update required a change to an existing field, such as nesting a value at a different level of the request body, or if a new required field is added to support new functionality, then those changes would be considered breaking and would result in a new API version being created.
The addition of new gallery modules should rarely, if ever, be a breaking change. When a new gallery module is enabled, people using your updater within their shortcut can immediately start using the module with no need for you to update anything in your updater.
The API can be accessed at https://updatekit.mikebeas.com.
New API releases will be announced via the UpdateKit Bluesky account.
Available Endpoints
The following endpoints are available for UpdateKit API v1.
API Details: GET /
Fetches configuration information about the API, including a list of natively supported third-party websites with their module keys. You can also see a list of version number comparisons that have been tested by the service's CI pipeline prior to deployment.
Check for Update: POST /v1
This endpoint is used to check for shortcut updates.
Bulk Check for Update: POST /v1/bulk
This endpoint is used to check multiple shortcuts for updates at once.
Checking for Updates
To check for an update to a self-hosted shortcut or one from an unsupported gallery website, use this body for your request.
{
  "shortcut": {
    "version": "1.0.0.0.0.0",
    "url": "https://example.com/shortcuts/shortcut-id"
  }
}
The shortcut object contains details about the shortcut being updated.
The version is the installed shortcut's current version number. It can contain any number of points and supports -tags for SemVer-like versioning. Generally, the UpdateKit API supports anything SemVer 2.0.0 supports, plus more. The only exception to the SemVer standard is that the UpdateKit API does not compare pre-release tags lexically. More information on tags can be found below.
The url is the address where an UpdateKit-compatible JSON file describing the latest version of your shortcut can be found. You can find more information about what this file should look like below.
The UpdateKit API is designed to support the addition of modules for communicating with shortcut gallery websites, including that do not conform to the UpdateKit data format standard. To use one of these modules, you will need to adjust the format of your request body.
{
  "shortcut": {
    "version": "1.0.0.0.0.0",
    "module": "routinehub",
    "id": "69"
  }
}
Notice that in this case, you do not need to include the url string, as the API module will be able to determine the proper URL automatically.
The module is a special keyword that tells the API which module to use. You can find a list of supported modules and their keywords by calling the API Details endpoint. New modules will be announced via the UpdateKit Bluesky account. Unless otherwise stated, all modules are supportted on all versions of the API.
The id value is the gallery website's specific ID for the shortcut being checked for updates. This will be used to create the URL, communicate with the site's API and perform the update check.
Checking for Updates in Bulk
The UpdateKit API supports checking multiple shortuts for updates in a single call. You can use the Bulk Check for Updates endpoint to submit an array of multiple shortcut objects. The API will return the total number of updates and the payload for each shortcut separately. An example body is below.
{
  "shortcuts": [
    {
      "version": "1.0.0.0.0.0",
      "url": "https://example.com/shortcuts/shortcut-id"
    },
    {
      "version": "1.1.0.0.0.1",
      "module": "routinehub",
      "id": "69"
    }
  ]
}
The shortcuts array is a list of shortcuts you want to update, using the same object structure you use for the single-shortcut Check for Update endpoint. You can also mix and match different updater modules within this array if needed.
Other API features such as the ability to obtain shortcut names and icons can also be used with this endpoint by including the appropriate properties as shown throughout this documentation.
In the UpdateKit API response to bulk requests, the payloads will be in the same order as the shortcuts submitted. However, only shortcuts with updates will be included in the payloads array, so you should not use the indexes as a means of matching shortcuts in the response to shortcuts in your request.
Getting Missed Update History
This feature is currently only available with Switchblade.
In some cases, your users may go a long time without installing an update to your shortcut. When that happens, getting only the latest available version can cause users to miss being notified about important changes from previous versions, since they will only see the release notes for the latest release.
To help in this situation, some galleries are able to return the full history back to the version currently installed on the user's device. You can request this information by including an includeMissed boolean in your request body.
{
  "shortcut": {
    "version": "7.0",
    "module": "switchblade",
    "id": "example.com:1"
  },
  "platform": "iPhone",
  "platformVersion": "16.0",
  "includeMissed": true
}
When this parameter is included, the API response includes a missedUpdates array that contains the full history back to, and including, the user's current installed version. You can iterate over this array to display the full list of updates your users have missed.
{
  "update": true,
  "payload": {
    "version": "8.0",
    "download": "icloud.com/",
    "notes": "This is a new release!",
    "release": "2020-10-30T12:00:00.000Z",
    "required": false,
    "missedUpdates": [
      {
        "version": "8.0",
        "download": "icloud.com/",
        "notes": "This is a new release!",
        "release": "2020-10-30T12:00:00.000Z",
        "required": false
      },
      {
        "version": "7.0",
        "download": "icloud.com/",
        "notes": "This is an older release",
        "release": "2019-10-30T12:00:00.000Z",
        "required": false
      }
    ]
  }
}
When checking for updates in bulk, you can set this separately for each shortcut object.
Getting Gallery Download URLs
If you prefer to get the download URL for the gallery website hosting your shortcut instead of the direct iCloud URL, you can set getOriginalDownloadUrl to true inside the shortcut object in your request body. This will only work for supported gallery sites. Unsupported sites will return the iCloud URL as usual.
{
  "shortcut": {
    "version": "1.0",
    "module": "routinehub",
    "id": "69",
    "getOriginalDownloadUrl": true
  }
}
When checking for updates in bulk, you can set this separately for each shortcut object.
Getting Shortcut Icons and Names
The UpdateKit API can optionally return a shortcut object containing metadata about the shortcut being checked for updates. Currently this metadata includes the shortcut name as reported by Apple's API (useful if the shortcut name provided to you by the shortcut is incorrect or has changed) and the base64-encoded shortcut icon.
To get all of this metadata with a single parameter, include the includeMetadata property in your POST body with a boolean true value.
{
  "shortcut": {
    "version": "1.0.0.0.0.0",
    "url": "https://example.com/shortcuts/shortcut-id"
  },
  "includeMetadata": true
}
Be aware that this is optional because it can increase the size of the response due to the inclusion of a full-size PNG image as base64, which will result in slightly slower response times. You should only request this metadata if you need the icon or have a need to validate the actual file name of the shortcut being provided to the user.
If you would prefer to select which metadata options to receive, you can specify an include array and name only the items you want. You do not need to include the includeMetadata parameter if you use this option. Using both together will not cause any issues, however, and your include array will be respected.
This may be useful if you want the names, but don't need the icons and want to reduce the overall download size of the API response. Note that this will not necessarily speed up the processing time on the UpdateKit API side, as it still needs to get the data from the iCloud API, but it will reduce the time needed for the user's device to download the response, depending on the speed of their internet connection.
Available metadata values that can be used in your include array are: name, icon.
{
  "shortcut": {
    "version": "1.0.0.0.0.0",
    "url": "https://example.com/shortcuts/shortcut-id"
  },
  "include": [
    "name",
    "icon"
  ]
}
Distributing Pre-Release Versions
You can use the UpdateKit API to distribute pre-release versions of your shortuct separate from your main production version by using the pre-release tags feature.
This notice does not apply to shortcuts hosted on Switchblade. If you distribute your shortcuts on Switchblade, betas will never block stable releases from appearing for end users.

There is one key limitation you should be aware of when distributing pre-release versions. Because the UpdateKit API pulls the latest version of your shortcut available from the server, it is possible that users who only want to see stable builds may not be shown a valid update because there is a newer pre-release version available.

Consider the following example: a user has version 1.0, version 1.1 stable has been released, and version 1.2-beta.1 is available. The UpdateKit API will see version 1.2-beta.1 as the latest version available, and will not see version 1.1, so it will not be shown it to the user. If the user has pre-release versions disabled, they will not see version 1.1 and will only see their next update available when version 1.2 stable is released, before the subsequent beta is released.

If you provide users a way to opt out of pre-release versions, you should leave a reasonable period of time after each stable release before publishing a new pre-release version so that users will have enough time to update.

I am investigating potential solutions to this issue for future versions of the UpdateKit API, but at this time the only way to work around this without imposing on everyone who operates a server that the API interacts with would be to download and check every version of a shortcut from the server and see which ones are or aren't pre-releases to find the latest stable version. Unfortunately this isn't feasible for a number of reasons, including the fact that some some sites, like ShareShortcuts, do not have any documented API for doing so.

If you want to run a constant pre-release program, it may be beneficial to keep your pre-release versions on a separate URL or shortcut listing on your gallery site of choice, and pass in a different module ID or URL depending on whether the user wants to see pre-release versions. If you intend on running pre-releases less often, running them on the same URL or gallery listing should be fine.
Tags appear at the end of a version number and are preceded by a hyphen (-). The tag indicates what level of pre-release a shortcut has reached, and a number indicates the number of versions within that pre-release state. The format looks like 1.2-beta.1 or 1.2-beta1 (with or without the dot between "beta" and "1"). Both of these are valid in the UpdateKit API. You can include as many dots in your tag as you want. You can also use multiple tags if you need to, such as -beta.alpha.1.rc.alpha, although this does not typically make sense from a practical standpoint.
Although the UpdateKit API makes every effort to support the full SemVer 2.0.0 standard, there is one main exception to note. If you use custom tags for your pre-release versions, you should order them as you want them. The UpdateKit API does not conform the SemVer standard of lexical comparison for these tags, and instead handles them in the order they are included in the tags array. The UpdateKit API's default tags, however, are ordered in such a way that this does not make a difference when using them.
As in SemVer, you can include other metadata following a + at the end of your version number. This will be ignored when comparing version numbers.
To trigger the UpdateKit API to check for pre-release versions, send a boolean called prerelease in your request body. If this is not true, the user will only get back the latest stable version of the shortcut. This allows you to give the user control over whether they want to see pre-release versions or not.
Your tags should be in a JSON array ordered from earliest stage of development to latest.
{
  "shortcut": {
    "version": "1.0.0.0.0.0",
    "url": "https://example.com/shortcuts/shortcut-id",
    "prerelease": true,
    "tags": [
      "alpha",
      "beta",
      "rc"
    ]
  }
}
You can also group together two tags that should be used at the same level by putting them into an array, as shown below with "alpha" and "a", which both refer to the same level of pre-release development.
{
  "shortcut": {
    "version": "1.0.0.0.0.0",
    "url": "https://example.com/shortcuts/shortcut-id",
    "prerelease": true,
    "tags": [
      [
        "a",
        "alpha"
      ],
      "beta",
      "rc"
    ]
  }
}
The default tags used by UpdateKit are shown below. If you want to use these in your shortcut, you do not need to include the array of tags with your submission.
[
  [
    "alpha",
    "a"
  ],
  [
    "beta",
    "b"
  ],
  "rc"
]
Skipping a Version
If your shortcut or updater allows users to choose to skip an update permanently until the next version becomes available, you can store the skipped version in your shortcut's preferences. During your update checks, you can inform the UpdateKit API of this decision and the API will take it into account when determining whether there is a new version available.
To take advantage of this feature, simply include a skip property in the shortcut object of your request body that indicates the version the user skipped. As long as this version is available, your shortcut will be told that no update is available.
{
  "shortcut": {
    "version": "1.0",
    "module": "routinehub",
    "id": "69",
    "skip": "6.0"
  },
  "platform": "iPhone",
  "platformVersion": "15.0"
}
The POST body above will show that no update is available if 6.0 is the latest version, even if your user is on a previous version of your shortcut. If your user resets this option in your shortcut and you do not send the skipped version, they will begin once again seeing updates. If they skip version 6.0, they will still see the next version when it becomes available (such as 6.0.1).
Aside from sending the UpdateKit API this new value, you don't have to do anything else to handle this situation. The API will simply return false if the user should not see an update. You don't need to do any checks on your end to see if the version they skipped is the same version that's available.
Specifying an iOS or Mac Version
The UpdateKit API allows you to optionally specify what operating system your updater is running on so that you can check for shortcut updates specific to that system version. This can help avoid showing updates to users that won't run on their device.
This feature must be supported by the gallery site that you are requesting updates from. If a specific gallery site does not support the feature, you can try asking the developer of the site to add support.
It's generally a good idea to go ahead and include this value if you think your updater will be used by shortcuts hosted on sites that support this functionality, or may be updated to support it one day.
To support this functionality, the gallery site needs to watch for at least one of two headers on the request to their API: system, which contains the major system version (15), and release, which contains the specific system version (15.1.1). Then they can look up shortcut versions in their system that correspond to the appropriate version or versions (remembering that shortcuts may be forwards-compatible).
A third header, platform is also included. This header will be a string equal to either ios or mac to indicate which platform the requested shortcut is running on. For gallery sites, it is good to keep in mind that Shortcuts on a specific Mac version will almost certainly correspond to the iOS version from that same year, since the app runs the same on both platforms. This may help you easily map shortcuts that are compatible with a specific iOS version to an equal Mac version.
To specify the platform and platform version when checking for an update, you can include the platform and platformVersion items in your POST body. You can populate platform with the output of the Get Device Details action (getting the device model value).
On newer versions of iOS, you can skip the Get Device Details action and use the built-in Device Details global variable. You can use the OS, Device Type, or Device Model value from this global variable. Any of these will work.
You can populate platformVersion with the output of the same action getting the system version. You do not need to modify these values in any way, the UpdateKit API can interpret the exact output of the actions and handle them as needed.
{
  "shortcut": {
    "version": "1.0",
    "url": "https://example.com/shortcuts/shortcut-id"
  },
  "platform": "iPhone",
  "platformVersion": "15.0.1"
}
{
  "shortcut": {
    "version": "1.0",
    "url": "https://example.com/shortcuts/shortcut-id"
  },
  "platform": "Mac",
  "platformVersion": "12.0.1"
}
Prior to support being added for platform and platformVersion, there was another method of sending this information, but it was more complicated to setup from inside a shortcut. This method still works in v1 and will be removed in v2. To use the legacy method, you need to include an ios or mac string in your POST body, as shown below. You can use the Get System Details action in Shortcuts to get this value easily.
The recommended method of setting this value is to simply set a variable in your shortcut to either ios or mac based on the results of the Get Device Details action with the Device Model option. For Macs, the output from this always seems to be Mac. Any other device types may be assumed to be iOS. Once that variable is set, you can use it as the key to this property in your JSON data.
The example shortcut (available from the "Example" button at the top of this page) shows this configuration in action.
iOS Example
{
  "shortcut": {
    "version": "1.0",
    "url": "https://example.com/shortcuts/shortcut-id"
  },
  "ios": "15.0.1"
}
Mac Example
{
  "shortcut": {
    "version": "1.0",
    "url": "https://example.com/shortcuts/shortcut-id"
  },
  "mac": "12.0.1"
}
UpdateKit API Response
The response to your request for an update check will be structured as shown below.
{
  "update": true,
  "payload": {
    "version": "6.0",
    "download": "https://www.icloud.com/shortcuts/b7e6382d4b52417cb6597b3f1d4af46f",
    "notes": "This version of RoutinePub is compatible with iOS 15. If you are not on iOS 15 it is recommended that you skip this version until you update.\r\n\r\nDue to changes made by Apple, you will need to copy the URL to your Shortcut before running RoutinePub and selecting the option to publish a new version.\r\n\r\nDue to the changes Apple made, RoutinePub is not able to take advantage of the previous “Shortcut Associations” feature anymore. Most of the feature was left intact in case Apple backtracks, but the menu option will just show a message and exit now. You will need to select which RoutineHub listing to update each time you publish an update.",
    "release": "September 11, 2021",
    "required": false
  }
}
If an update is available, update will be true and there will be a payload containing the details of the update. If there is no update available, update will be false and no payload will be included.
The version in the payload is the new version of the shortcut that is available.
The download URL is the iCloud link to download the latest version of the shortcut. If you set getOriginalDownloadUrl to true, this will be the download URL on the gallery website, for modules where this is supported.
The notes string will include the release notes for this version.
The release value, which is optional in the UpdateKit data format standard, is the release date of this version. It may not be included in all cases.
The required value, which is optional in the UpdateKit data format standard, is a boolean value indicating whether this update is required to be installed by the developer. See the UpdateKit Data Format section for more information. This value may not be included in all cases and can be assumed false if not present.
If you requested the shortcut metadata with your update check, you will also get additional information in the response, as shown below.
{
  "update": true,
  "payload": {
    "version": "9.0",
    "download": "https://www.icloud.com/shortcuts/be953510c9094f09b4278ad86043d377",
    "notes": "UpdateKit 9.0 is compatible with iOS 15. It has been tested with iOS 15.2 beta 1 and should work on earlier versions, but I am not able to confirm that due to Apple having broken a number of things in various builds of iOS 15. Please note that UpdateKit has not been tested on Mac and may not work there.",
    "release": "October 28, 2021",
    "required": false,
    "shortcut": {
      "name": "UpdateKit",
      "icon": {
        "base64": "[base64-encoded icon removed in this example due to length]"
      }
    }
  }
}
UpdateKit Data Format
Any gallery website (or developer's personal website) that uses the following data structure for their API responses will automatically be supported through the UpdateKit API's generic URL module. You can begin using these sites immediately by specifying the url described above.
VersionRequired
The Version is the version number of the latest version to be released.
URLRequired
The URL value points to the iCloud sharing URL for the latest version.
NotesRequired
The Notes value is a short message that indicates what changes have been made in this version.
ReleaseOptional
The Release value contains the release date for the latest version. This may be formatted however you want, although you may want to have a human-readable date format in case an updater displays the value.
RequiredOptional
The Required value indicates whether this update is required to be installed by the user. This can be checked by your updater or shortcut to determine if the user should be allowed to skip the update. Some examples of instances where you might want to force users to install an update would be a situtation where a shortcut that communicates with a server requires changes in order to continue functioning, or where using the old version might create a security risk for the user.
An example of this file format is shown below.
{
  "Version": "1.0",
  "URL": "https://www.icloud.com/shortcuts/1f40b16a82c04e989261dfb0054928d0",
  "Notes": "UpdateKit initial release.",
  "Release": "September 23, 2018",
  "Required": true
}
Best Practices for Gallery Sites
If you would like the UpdateKit API to support a module for your gallery site, you can follow this guide to get the most out of the integration. Be sure to document any of the features below that are supported by your API so they can be integrated into the module. Once you've documented your API, let me know via Bluesky and I will work with you to get the module up and running.