Custom URL scheme

The Hit List supports a custom URL scheme for controlling some aspects of the application.

Look up by UID

Every group and task in The Hit List is internally given a unique ID. Clients that know such an ID can request the group or task be opened. On the Mac, you can get this kind of URL for a task by choosing “Copy as Link” in the Edit menu.

Availability: Mac

Look up lists or folders by name

The route to a list is specified as a path in the URL, using the name of each group. Some examples:

URL Explanation
thehitlist:///Inbox Opens the Inbox
thehitlist:///Bucket%20List Opens a list or folder named “Bucket List”
thehitlist:///Projects/Shed Opens a list or folder named “Shed”, inside of the folder “Projects”

Names are handled case-insensitively, so you can specify either inbox or Inbox, for example. Non-URL path characters — such as spaces — need to be percent encoded. See “Bucket List” above, for example.

Availability: Mac

Create tasks

As above, the URL path specifies which list the task should be created in. The URL query begins at the ? character. The query is composed of a series of parameter names and values separated by ‘&’ symbols. A ‘=’ character is used to separate parameter name and value.

Spaces are accepted as either a ‘+’ symbol for convenience, or as the full %20 sequence. Consequently, if you require an actual ‘+’ character, it must be encoded as %2B.

Parameter names are case-insensitive. Parameters may appear in any order. Unrecognized parameter names or values are ignored. The result of duplicate parameter names is undefined. If the specified list does not exist, the request goes ignored.

Parameter Explanation Availability
title Title of the new task. As when typing in a task, / or @ may be used to specify a tag. Mac and iOS
notes Notes to include in the task Mac and iOS
url The URL to include in the task notes Mac and iOS
urlTitle The name of the link for the URL Mac
startDate, dueDate Dates can be specified using the shorthand values that The Hit List application understands. For example, “6/4”, “June 4, 2010”, “4” (4th of the next month), “wed”, “4d” (in four days), “today”, “t” (today), and so on and so on. If you add a task to the Today group, the start date gets automatically set to today. Mac and iOS, although iOS only supports a limited range of date formats
estimatedTime Example values are 30m, 0.5h 1d, and so on Mac and iOS. Time estimates aren’t visible in the iOS app, but they will show up when synced back to a Mac.
priority Priority can range from 0 to 9 where 0 is no priority. In the iOS app, priorities 1 & 2 are red, 3 & 4 yellow, 5 grey, 6 & 7 blue, and 8 & 9 green. Mac and iOS
index An index value of n will insert to that index in the list. Index of -1 is a special case where it will add to the end of the list. The default is 0. Mac


Creates an empty task in the Inbox.


Creates a task named “Swim with dolphins” in “Bucket List”. Notes are filled in with “Perhaps in Mexico?”


Creates a task tagged with @work. On iOS, the leading space places the text insertion point at the start of the title, ready to type. You can specify a trailing space instead to automatically start typing after the tag.


Creates a task with the due date 24 June 2015.