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.



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



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 a new task. For example, create a new task with title"Read chapter 3”:



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’.




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.


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




Pause the current timer.





If you have further questions please get in touch.