# Expose Selected Synced Shortcuts as App Actions

Canonical: https://figment.so/blog/synced-shortcuts-api

Apple has no public API for running user-created Shortcuts. App Intents lets developers publish up to ten app-defined intents into the Shortcuts app ([WWDC 2022, session 10170](https://developer.apple.com/videos/play/wwdc2022/10170/)), but that surfaces developer-owned code to users—it does not give a server-side app access to the shortcuts a user has already built.

This guide covers the reverse direction: a user's iCloud-synced shortcuts become named, typed actions your backend can invoke. The execution surface is a Figment-hosted Mac. The grant and receipt layer is a developer-owned adapter your team builds on top of the connection. No Figment-supplied endpoint for shortcut listing or execution exists; the design below is an integration pattern, not a ready-made product feature.

## How iCloud Shortcuts sync reaches the Mac

The Shortcuts app synchronizes a user's entire collection across iPhone, iPad, Mac, Apple Watch, and Apple Vision Pro via iCloud. To enable sync on Mac, the user opens the Shortcuts app, chooses **Shortcuts → Settings**, and enables **iCloud Sync** in the General pane. Additions, edits, deletions, and shortcut order mirror automatically across every device on the same Apple Account ([Apple Support](https://support.apple.com/guide/shortcuts-mac/sync-shortcuts-apdb3a4240b0/mac)).

This synced library is the pool your adapter reads from.

**One constraint is firm.** Only Mac-compatible, installed actions can execute on the connected Mac. A shortcut built entirely from iOS-only steps appears in the library but will not run there. Record Mac compatibility at grant time, not at invocation time, so your app never attempts to call an action the Mac cannot run.

## Per-shortcut grant design

The user selects specific shortcuts during Figment's app consent flow—a separate step from the initial Apple Account connection setup. Your adapter records only those selections. Your app receives a bounded, enumerable action set, not a catch-all permission to invoke anything in the user's library.

Three properties follow from this design:

- **Privacy.** The user knows exactly which shortcuts your app can reach.
- **Auditability.** Each invocation maps to a named, stable identifier in your records.
- **Predictability.** Your integration handles a fixed list of typed actions rather than an unbounded unknown set.

## Action schema

For each approved shortcut, record enough to validate and dispatch a call before the first invocation. A minimal schema entry:

| Field | Description |
|---|---|
| `shortcutId` | Stable internal identifier assigned at grant time |
| `name` | Display name from the user's library at grant time |
| `inputType` | Expected input: `text`, `json`, `file`, or `none` |
| `outputType` | Declared output: `text`, `json`, `image`, or `none` |
| `macCompatible` | `true` if the shortcut can execute on the connected Mac |
| `grantedAt` | ISO timestamp of the user's approval |

```json
{
  "shortcutId": "shct_7xQpR4mN",
  "name": "Summarize Clipboard",
  "inputType": "text",
  "outputType": "text",
  "macCompatible": true,
  "grantedAt": "2026-11-12T10:00:00Z"
}
```

Build your integration around `shortcutId`, not `name`. If the user renames the shortcut in their library, the identifier stays stable and the grant record stays valid.

## Execution and result receipt

The macOS `shortcuts` command-line tool is the execution surface. Your Mac-side adapter invokes it for approved shortcuts and returns a receipt your app can poll. The companion guide [Run Mac Shortcuts from the Command Line](/blog/mac-shortcuts-command-line) covers the CLI mechanics in full; the key adapter design points are:

**Persist intent before dispatch.** Store the shortcut ID, input, idempotency key, and connection ID in a durable store before the first call. A network timeout must not lose the key.

**One key per intended action.** Generate a stable key tied to the specific business action, not a hash of the payload alone. Two separately intended invocations of the same shortcut with the same input must carry different keys.

**Receipt states.** A minimal receipt design maps to these states:

| State | Meaning |
|---|---|
| `submitted` | Adapter accepted the request; Mac execution pending |
| `running` | Mac is actively executing the shortcut |
| `completed` | Execution finished; output is available |
| `failed` | Shortcut returned an error or was cancelled |
| `unknown` | Outcome not yet determinable |

**Never issue a new key for an `unknown` outcome.** The shortcut may have already executed and produced a side effect. Poll the receipt with the original key. Use a new key only after a confirmed failure or a deliberate new intent.

**Offline connections queue.** If the Figment connection status is `offline`, submissions queue until the Mac reconnects. For latency-sensitive workflows, check connection status first and return a user-facing message rather than queuing silently.

## Related guides

Shortcuts work well alongside other Apple data sources. A shortcut that processes notes, files, or calendar events can be paired with read access to those stores through the same connection:

- [Run Mac Shortcuts from the Command Line](/blog/mac-shortcuts-command-line) — `shortcuts run`, output parsing, and iteration before integration
- [OAuth for iCloud: Connect Apple Data to Your App](/oauth-for-icloud) — connection setup and app consent flow
- [Connect Apple Notes, Photos, Files, and Safari](/apple-data-connectors)
- [Create Apple Reminders with EventKit on Mac](/blog/apple-reminders-eventkit)

[Connect Apple Account](/apple-connect/developers) to start the connection setup and explore the sandbox.