Focus URL Scheme

The URL scheme is for pro users and developers who want to interact with Focus through a custom URL.

 

In addition to drag & drop and the system share sheet, the custom URL scheme is a great way to send data and commands directly to Focus. It works on both iOS and macOS starting with Focus 5.2.

 

Schema

Here’s the schema for communicating with Focus via URL:

focusapp://command?parameter1=value1&parameter2=value2

 

Support for x-callback-url

All commands support the x-callback-url convention by calling the provided x-success, or x-error callbacks as appropriate. The add command returns the id of the newly created task as a parameter to the x-success callback.

Available commands are:

add

Add a new task. For example, create a new task with title"Read chapter 3”:

focusapp://add?title=Read%20chapter%203

Parameters:

title – String. The title of the new task.
note – String. The note of the new task.
sourceURL – String. When you want to link a task to an item from another app (e.g. a task in OmniFocus) specify a source link that directly points to that task in the other app. E.g. a task in OmniFocus can be accessed by omnifocus:///task/taskID where taskID is the identifier of the task. If you specify a sourceURL that is supported (currently: OmniFocus, Mail, Safari), a tappable icon will be created next to the task to open the source.
sessionEstimate – Number. The estimated number of sessions that will be needed to complete the task, e.g. ‘8‘. If you specify a sessionEstimate and a minutesEstimate, only the minutesEstimate will be used.
minutesEstimate – Number. The estimated number of minutes that will be needed to complete the task, e.g. ‘240’.
due – String. Possible values: today, tomorrow or a date string of the form yyyy-mm-dd. E.g. 2019-03-24. Focus will also attempt to interpret natural language dates such as in 2 days or next Monday. These must be provided in English.

All parameters are optional but a task must have at least a title or a note. The x-success callback will be called with the identifier of the new task (String) for the parameter ‘id’.

Examples:

focusapp://add?title=Read%20chapter%204&note=Pages%20304-328
focusapp://add?title=Prepare%20Presentation&note=Referecene%20mail%20notes&sessionEstimate=8&due=monday
focusapp://add?title=Study%20documentation&note=make%20notes&minutesEstimate=120&due=tomorrow

delete

Delete a task by using its identifier.

Parameters:

id – String. The id of the task.
ids – String. Ids of the task, separated by ‘?’

Examples:

focusapp://delete?id=B1127BC6-3CC3-4AC4-B561-3CD493D2EDD6
focusapp://delete?ids=B1127BC6-3CC3-4AC4-B561-3CD493D2EDD6?U36SAM-3CD3-1BC4-B481-2CD590D2EDD2

start-timer

Start the Focus timer. You can specify if you want to start a work session or a break and the associated duration. Both parameters are optional.

Parameters:

type – The type of the session: ‘focus’ or ‘break’.
duration – Number. The duration in minutes, e.g. ‘25’.

Examples:

focusapp://start-timer
focusapp://start-timer?duration=20
focusapp://start-timer?type=focus&duration=40

pause-timer

Pause the current timer.

Example:

focusapp://pause-timer
Focus