Focus URL Scheme

Last updated 17 July 2026

The URL scheme is for power users and developers who want to interact with Focus through a custom URL — from Apple's Shortcuts app, a launcher, or your own scripts and tools.

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.

The URL Format

Every command follows the same pattern:

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

Remember to percent-encode parameter values, so a title like "Read chapter 3" becomes Read%20chapter%203.

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.

add — Add a New Task

Adds a new task. For example, this creates a task titled "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 points directly to that item in the other app. A task in OmniFocus, for example, can be reached via 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 appears next to the task to open the source.
• sessionEstimate — Number. The estimated number of sessions needed to complete the task, e.g. 8. If you specify both a sessionEstimate and a minutesEstimate, only the minutesEstimate is used.
• minutesEstimate — Number. The estimated number of minutes 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 needs at least a title or a note. The x-success callback is called with the identifier of the new task (String) in the parameter id.

Examples:

focusapp://add?title=Read%20chapter%204&note=Pages%20304-328

focusapp://add?title=Prepare%20Presentation&note=Reference%20mail%20notes&sessionEstimate=8&due=monday

focusapp://add?title=Study%20documentation&note=make%20notes&minutesEstimate=120&due=tomorrow

delete — Delete a Task

Deletes a task by its identifier.

Parameters:

• id — String. The id of the task.
• ids — String. Ids of several tasks, 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 Timer

Starts the Focus timer. You can specify whether to start a work session or a break, and the 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 Timer

Pauses the current timer.

Example:

focusapp://pause-timer

No URLs Needed for the Basics

If you'd rather not build URLs by hand, that's fine too — Focus also works with Siri and Apple's Shortcuts app directly, no URL scheme required. The links above are there when you want finer control from scripts and other apps.

Questions or ideas? We'd love to hear from you at hello@meaningful-things.com.