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.

 

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

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

 

 

If you have further questions please get in touch.