Things provides a variety of actions for Apple’s Shortcuts app so that you can build your own workflows. This page is the technical documentation for this feature.

If you’re new to Shortcuts, the best way to get started is by downloading and exploring the example shortcuts we provide in our introductory article: Using Apple Shortcuts. You can also review Apple’s documentation for Mac, iPad, and iPhone. Come back to this page once you’re ready to build your own shortcuts.

Below are all the actions that Things provides. You can customize an action by setting different values for its parameters. Some actions also return a value upon completion.

Minimum requirements: Things 3.17 and macOS 14, iPadOS 17, iOS 17, visionOS 1.

Things Actions
  1. Create
  2. Find
  3. Edit
  4. Show
  5. Advanced

In addition to Shortcuts’ built-in types, Things uses two custom types:

Things Custom Types
  1. Item New
  2. List New

See the bottom of this page for tips, known issues, and frequently asked questions.



Item Type

Most of Things’ actions operate on Items (single or multiple). An item can be a to-do, a heading, a project, or an area. For example, if you use the Find Items action to find all items that have a particular tag, the resulting items could contain areas, projects, and to-dos. You can then show them inside of Things by passing them to the Show Items action, edit them all at once by passing them to the Edit Items action, and so forth.

Not all properties are available for each type of item. For example, an item of type To-Do does have a Checklist, but items of type Heading, Project, or Area do not. If you access these properties anyway, they are simply empty. You can determine the type of an item by inspecting its Type property.

Properties

Type
The item’s type: To-Do, Heading, Project, or Area.
Title
The item’s title. Available for all item types.
Parent
The parent the item is contained in, if any. For a to-do, this can be a project or an area. For a heading, this is its project. For a project, it is its area, if any. Not available for areas.
Heading
The heading the item is under, if any. Only available for to-dos.
Is Inbox
Whether of not the item is in the Inbox. Only available for to-dos.
Start
The item’s start: On Date, Anytime, or Someday. If set to On Date, further information is available via Start Date, Evening, and Reminder Date. Only available for to-dos and projects.
Start Date
The item’s start date, if any. The time component is always set to midnight. Only has a value if Start is set to On Date. Only available for to-dos and projects.
Evening
Whether or not the item is planned for the evening. Only applicable if Start is set to On Date and Start Date is today’s date. Only available for to-dos and projects.
Reminder Date
The item’s reminder date, if any. Includes both a date and time component. The date component is equal to the item’s start date, and the time component is set to when the reminder will fire. Only applicable if Start is set to On Date. Only available for to-dos and projects.
Deadline
The item’s deadline date, if any. The time component is always set to midnight. Only available for to-dos and projects.
Tags
A list of the titles of every tag that has been directly applied to the item, if any. Only available for to-dos, projects, and areas.
All Matching Tags
A list of all Tags, plus the titles of all inherited tags. Useful mostly when using the Find Items action. Only available for to-dos, projects, and areas.
Status
The item’s status: Open, Completed, or Canceled. If set to Completed or Canceled, the completion date is available via Completion Date. Only available for to-dos, headings, and projects.
Completion Date
The item’s completion date, if any. Only applicable if Status is set to Completed or Canceled. Only available for to-dos, headings, and projects.
Is Logged
Whether of not the item is logged. Only available for to-dos, headings, and projects.
Notes
The item’s notes, if any. Only available for to-dos and projects.
Checklist
The item’s checklist, if any. Each checklist item is separated with a newline. Only available for to-dos.
Creation Date
The item’s creation date. Only available for to-dos, headings, and projects.
Modification Date
The item’s modification date. Only available for to-dos, headings, and projects.
ID
The item’s unique identifier. Available for all item types.
Parent ID
The unique identifier of the parent the item is contained in, if any. For a to-do, this can be a project or an area. For a heading, this is its project. For a project, it is its area, if any. Not available for areas.

List Type

A List represents any list that can be displayed inside of Things. These are:

  • Built-in lists that are always shown in the sidebar or source list.
    • Inbox
    • Today
    • Upcoming
    • Anytime
    • Someday
    • Logbook
  • Built-in lists that are hidden, but can be navigated to via Quick Find.
    • Tomorrow
    • Deadlines
    • Repeating
    • All Projects
    • Logged Projects
  • User-created lists.
    • One for each of the user’s Areas
    • One for each of the user’s Projects
    • One for each of the user’s Tags (hidden, but can be navigated to via Quick Find)

Properties

Currently, this List type can only be used in the Open List action. It has no properties that you can access.

Create To-Do Action

Creates a new to-do. All parameters are optional. If Parent or Start are not specified, the to-do will be created in the Inbox. If you want to show the to-do in Things after it’s created, connect a Show Items action.

Parameters

Title
The desired title of the to-do.
Parent
The project or area the to-do should be added to.
Heading
The heading the to-do should be under. If specified, the Parent parameter must be set to the same project the heading is in.
Start
The desired start of the to-do: On Date, Anytime, or Someday. If the value is set to On Date, three additional parameters can be specified:
  • Start Date The desired start date of the to-do. Accepts natural language like “tomorrow” or “in 7 days”. Does not support a time value.
  • Evening Whether or not the to-do should be planned for the evening. Ignored if Start Date is not set to today’s date.
  • Reminder Time The time when the reminder should fire (on the start date). Supports 12 or 24-hour formats, e.g. 8:15pm or 20:15.
Deadline
The desired deadline of the to-do. Accepts natural language like “tomorrow” or “in 7 days”. Does not support a time value.
Tags
The desired tags of the to-do.
Status
The desired status of the to-do: Open, Completed, or Canceled. If not specified, the status will be Open.
Notes
The notes that should be added to the to-do.
Checklist
The checklist items that should be added to the to-do. To add multiple items, use newlines. To set their status use Markdown.
Show When Run
Whether or not the action’s result should be shown in Siri’s UI at runtime.

Return Value

The newly created Item (a to-do).

Create To-Do with Quick Entry Action

Identical to the Create To-Do action, except that its output will be sent to the Quick Entry dialog so that you can further edit the to-do before saving it. On iPhone, iPad, and Vision, this will force Things to foreground; on Mac only the Quick Entry dialog will appear.

If all you want to do is invoke Quick Entry, simply leave its parameters empty.

Return Value

Nothing. The to-do you create does not exist as an Item in Things until you manually save it. This means there’s no Item to pass as output to other actions (e.g. you can’t reveal it with a Show Items action).

Create Heading Action

Creates a new heading inside of a project. Projects are the only lists that support headings.

Parameters

Title
The desired title of the heading.
Project
The project the heading should be added to.
Show When Run
Whether or not the action’s result should be shown in Siri’s UI at runtime.

Return Value

The newly created Item (a heading).

Create Project Action

Creates a new project. All parameters are optional. If you want to show the project in Things after it’s created, connect a Show Items action. If you want to populate your new project with to-dos, append some Create To-Do actions and pass your new project as their parent list.

Parameters

Title
The desired title of the project.
Area
The area the project should be added to.
Start
The desired start of the project: On Date, Anytime, or Someday. If the value is set to On Date, three additional parameters can be specified:
  • Start Date The desired start date of the project. Accepts natural language like “tomorrow” or “in 7 days”. Does not support a time value.
  • Evening Whether or not the project should be planned for the evening. Ignored if Start Date is not set to today’s date.
  • Reminder Time The time when the reminder should fire (on the start date). Supports 12 or 24-hour formats, e.g. 8:15pm or 20:15.
Deadline
The desired deadline of the project. Accepts natural language like “tomorrow” or “in 7 days”. Does not support a time value.
Tags
The desired tags of the project.
Status
The desired status of the project: Open, Completed, or Canceled. If not specified, the status will be Open.
Notes
The notes that should be added to the project.
Show When Run
Whether or not the action’s result should be shown in Siri’s UI at runtime.

Return Value

The newly created Item (a project).

Find Items Action

Queries Things for items that match one or more filters. If you want to show the results in Things, connect a Show Items action.

Apple completely broke the Find action with the release of macOS 14.4 and iOS/iPadOS 17.4. The bug also affected actions for some of their own apps (e.g., Notes, Clock). We filed feedbacks (FB13686972, FB13686986) and they appear to have fixed it with the release of macOS 14.5 and iOS 17.5. If you are experiencing issues, make sure you’re running the latest OS versions. How to check your versions.

Parameters

Filters:
  • Type Return items that are (or not) to-dos, headings, projects, or areas.
  • Title Return items with the specified string in the title.
  • Parent Return items that are (or not) inside the specified project or area.
  • Is Inbox Return items that are in the Inbox.
  • Not Is Inbox Return items that are not in the Inbox.
  • Start Return items whose “When” property is (or not) set to: On Date, Anytime, or Someday.
  • Start Date Return items with a start date that matches the specified date, or range of dates. Shortcuts requires you to specify a time here, but it will be ignored; it is not interpreted as a reminder time.
  • Evening Return items that are in This Evening.
  • Not Evening Return items that are not in This Evening. This includes all items that are not even in Today.
  • Reminder Date Return items with a reminder date that matches the specified date-time, or a range of date-times. The reminder date is equal to the item’s start date, with the time component set to when the reminder will fire.
  • Deadline Return items with a deadline date that matches the specified date, or range of dates.
  • Tags Return items that have the specified tag applied.
  • All Matching Tags Return items that have the specified tag, either applied directly, or via inheritance.
  • Status Return items that are (or not) Open, Completed, or Canceled.
  • Completion Date Return items with a completion date that matches the specified date-time, or range of date-times. The time component of the specified date does make a difference.
  • Is Logged Return items that have moved to the Logbook. This is not necessarily all items that have been completed.
  • Not Is Logged Return items that have not moved to the Logbook.
  • Notes Return items with the specified string in the notes.
  • Creation Date Return items with a creation date that matches the specified date-time, or range of date-times. The time component of the specified dates does make a difference.
  • Modification Date Return items with a modification date that matches the specified date-time, or range of date-times. The time component of the specified dates does make a difference.
  • ID Return an item with the specified ID.
  • Parent ID Return items that are (or not) inside the project or area with the specified ID.
Sort by
Sort the results by a chosen method:
  • By Title
  • By Start Date
  • By Reminder Date (including time)
  • By Deadline date
  • By Completion Date (including time)
  • By Creation Date (including time)
  • By Modification Date (including time)
  • By Random ✨
Limit
Return only a limited number of items.

Return Value

All Items that match the specified filters, sorted in the specified order. Results are limited to a maximum of 500 items.

Get Items Action

Lets you specify multiple items of a given type, which are then returned by this action.

Parameters

Type
The type of the items: To-Do, Heading, Project, or Area.
Items
The items that should be returned by the action.

Return Value

The specified Items.

Get Selected Items Action

Gets the items that are currently selected in Things. If multiple Things windows are open, the last active window is used.

Return Value

The selected Items.

Edit Items Action

Modifies a property of one or more Things items. Use with caution: changes made by this action cannot be undone.

You will receive a warning each time this action attempts to edit more than 99 items at once. This warning can be turned off in Things’ Settings.

Parameters

Edit
This first field adapts to perform different functions depending on the detail parameter that’s targeted in the second field.
  • Set Replace the detail parameter’s value with a new value.
  • Append/Prepend Available when editing e.g. the title, notes, or checklist. Lets you keep the existing value, and append or prepend a new string.
  • Add/Remove/Remove All Available when editing e.g. the tags. Lets you keep the existing tags, and add or remove specific ones.
Detail
The property of the items you want to modify:
  • Title The title of the item.
  • Parent The project or area the item should be in.
  • Start The start date of the item. Choose On Date to set a particular day. Supports natural language.
  • Reminder Time The reminder time of the item. The date component is ignored, if specified. Instead, each item keeps its start date.
  • Deadline The deadline of the item.
  • Tags The tags of the item.
  • Status The status of the item.
  • Completion Date The completion date of the item.
  • Notes The notes of the item.
  • Checklist The checklist items of the item. To append or prepend multiple rows, use newlines. To set their status, use this syntax.
  • Creation Date The creation date of the item.

    • Return Value

    The edited Items.

    Duplicate Items Action

    Duplicates one or more Things items. If you want to show the duplicated items in Things, append a Show Items action. Duplicating areas is not supported.

    Parameters

    Items
    The to-dos, headings, or projects to be duplicated.

    Return Value

    The duplicated Items.

    Delete Items Action

    Deletes one or more Things items. Use with caution: changes made by this action cannot be undone.

    You will receive a warning each time this action attempts to delete more than 99 items at once. This warning can be turned off in Things’ Settings.

    Parameters

    Items
    The items that should be deleted. Only supports to-dos, headings, and projects. Areas are ignored. When deleting a project, all items contained within it are also deleted; when deleting a heading, all items under it are also deleted.
    Delete Immediately
    If set to OFF, items are moved to the Trash. If set to ON, items are deleted immediately. iPhone, iPad, and Vision don’t have a Trash at this time, so the action will fail with an error on those devices unless you turn this setting to ON.

    Open List Action

    Opens Things and shows the specified list.

    Parameters

    List
    The list to show in Things. See List Type for more info.
    Filter by Tags
    The tags the list should be filtered by.

    Show Items Action

    Opens Things and shows the items passed into the action. If you pass a single item, it will be shown inside its parent list. If you pass multiple items, they will be shown together in a special list.

    Parameters

    Items
    The items to show in Things. See Item Type for more info.

    Run Things URL Action

    For backwards compatibility, you can use Run Things URL to utilize Things’ URL scheme. The benefit of using this action (rather than Safari’s Open URLs action) is that it can run the URL in the background without forcing Things to open.

    Parameters

    Things URL
    The URL. Looks like things:///add?title=Milk. Can contain variables. Some commands require your auth-token.




    Tips, Known Issues & FAQs

    Working with dates

    • The Adjust Date action is your friend. When using Things’ Find action, you may want to filter for items before or after the current date. Shortcuts’ Current Date variable also includes the current time. What you really want, in many cases, is the beginning of the current day (12:00 AM). For this, add an Adjust Date action, and set it to Get Start of Day.
    • Avoid using the Format Date action. Things’ actions accept the default date format provided by Shortcuts’ own date-related actions, so there is no need to reformat dates; doing so may cause a shortcut to fail.
    • Avoid using Ask Each Time for dates. See Using Ask Each Time.
    • In the Find action, avoid comparing dates via is in the last X days/months/years as it will yield incorrect results. For example, if you select Deadline is in the last 10 days, it will correctly filter out items that have a deadline older than 10 days, but it will include all items with deadlines in the future. This is a Shortcuts bug. As a workaround, target the date range using is between. FB11841259
    • In the Find action, avoid querying for a date range using is in the last as it will fail. This is a Shortcuts bug which appeared in either iOS 16.3 or 16.4. As a workaround, get the start of the range and use is after, or is between the start of the range and the current date. FB12392280
    • In the Find action, check if a date is today via is Today. Do not use is between in this case as it will yield incorrect results. This is a workaround for a Shorcuts bug. FB11799692

    Using Ask Each Time

    Apple has broken Ask Each Time when using the Find action on macOS 15. The bug also affects actions for some of their own apps.

    Almost all parameters of our actions support selecting Ask Each Time instead of a value. This way, you’ll be prompted to specify the value when you run your shortcut. But there are a few caveats:

    • Avoid using Ask Each Time for dates. We’ve found that Shortcuts sometimes produces strange output, especially if you live in a timezone east of GMT. Use the Ask for Input action instead, and pass its output. FB11969030
    • In the Find action, when you want to Ask Each Time for the Parent, the picker you see at runtime is not great. We recommend that you instead use Things’ Get Items action and pass its output to the filter. Check out this demo shortcut. FB11658481

    Building complex projects

    To create projects that contain both headings and to-dos, follow the steps below. You can also check out this demo shortcut.

    1. Create a new project with Create Project.
    2. Create a new heading with Create Heading, and pass the project from step 1 as the Project.
    3. Create a new to-do with Create To-Do, pass the project from step 1 as the Parent and the heading from step 2 as the Heading.

    Using the Find action

    Apple completely broke the Find action with the release of macOS 14.4 and iOS/iPadOS 17.4. The bug also affected actions for some of their own apps (e.g., Notes, Clock). We filed feedbacks (FB13686972, FB13686986) and they appear to have fixed it with the release of macOS 14.5 and iOS 17.5. If you are experiencing issues, make sure you’re running the latest OS versions. How to check your versions.

    Apple has broken Ask Each Time when using the Find action on macOS 15. The bug also affects actions for some of their own apps.

    Things’ Find action is built on top of an API provided by Apple that has many bugs and quirks that are beyond our control. Note the following caveats:

    • If you want to use filters that work with dates, please take a look at the Working with dates section.
    • Issues with the Parent parameter:
      • Broken in macOS 14 & iOS 17: Apple has broken the Find action’s Parent parameter on macOS 14 & iOS 17; it no longer remembers which parent you set. This means that when you close and reopen your shortcut, the parameter will be un-set (the parent will be gone). As a ramification, it means that when your shortcut runs, it will choose a different parent than expected, which may lead to actions being performed on the wrong items. To prevent data loss we’ve temporarily prevented the action from running and you will see an error. As a workaround, use the Get Items action to get the parent, then pass its ID into the Find action’s Parent ID parameter.
      • We don’t recommend using Ask Each Time to select a Parent. See the Ask Each Time section in this document.
    • It is not possible to configure a filter that returns items with no Deadline, or no Parent. This is a Shortcuts limitation. FB11797131
    • It is not possible to configure a filter that return items with no Tags.
    • When passing an input to the Find action so it turns into a Filter, it is not possible to filter the passed items based on their Type, Status, or Start properties. This is a Shorcuts bug. As a workaround, you can iterate the items manually and filter them with an If inside the loop. FB11939711
    • If you’re on an OS older than iOS 17/macOS 14, avoid modifying a filter after you’ve configured it. For example, don’t change it from filtering based on the Title to checking Is Logged. This can crash the Shortcuts app and render your entire shortcut broken. Instead, always remove the previous filter, and add a new one. This is a Shortcuts bug that was fixed only in iOS 17/macOS 14 and later. FB11939732

    Using the Edit action

    • If you use the Edit action to Set Status of a completed to-do to Open (incomplete)—but that to-do is also under a heading which has been archived—the to-do will be marked incomplete but will stay in the Logbook. This is the intended behavior.

    Using the If action

    • Broken in macOS 14 & iOS 17: If you use Apple’s If action to check if a Things item’s Parent is or is not you will not be able to set a value. This is a Shortcuts bug. You may be able to work around it by instead querying If Parent ID is ID.

    Limitations

    • Specifying a heading in the Create To-Do with Quick Entry action is not supported. This is a Shortcuts bug. FB11859240
    • A Share Sheet cannot get an item from Things as an Item, it can only get an item’s title (as text), so items cannot be passed into a shortcut this way. Instead, use the Get Selected Items action.
    • To run a Delete Items action on iPhone, iPad, or Vision, it must be set to Delete Immediately. This is because Things on these devices doesn’t have a trash at this time.
    • The Run Things URL action can only be used for URLs that don’t require Things to be foregrounded. For example, it will not work for things:///show?id=today. Use Shortcuts’ built in Open URLs action as a workaround. This is a Shortcuts limitation. FB11520039
    • You can’t use an If to check if an item’s Parent is equal to another item, as the UI won’t let you specify it. The workaround is to use the item’s Parent ID instead. This is a Shortcuts bug. FB11892632

    Other known issues

    • Sometimes the Shortcuts app shows strange or ugly names for the actions and their parameters. This is a Shortcuts bug. Restarting the app usually fixes this. FB11969021, FB11513036
    • If you’re an Apple engineer working on Shortcuts or App Intents… 👋 Please check the feedback numbers sprinkled above, and also these.
    Related Articles