URL Schemes

2Do for Mac registers the twodo:// URL scheme. Any app that can open a URL — Shortcuts, scripts, browsers, launchers, text expanders, and other automation tools — can use it to send commands to 2Do.

The public URL scheme is for user automation. It does not include sign-in, sync authorization, or other account callback URLs.

Base Format

Most actions use the x-callback-url format:

twodo://x-callback-url/<action>?<parameter>=<value>&<parameter>=<value>

Action names are case-insensitive, so showtoday, showToday, and ShowToday all reach the same action.

URL Encode Your Values

URL parameters must be encoded before you put them into a URL. This matters for spaces, commas, ampersands, line breaks, and symbols.

Text	Encoded
Buy milk	Buy%20milk
Work & Home	Work%20%26%20Home
finance,admin	finance%2Cadmin
Line one + line break + Line two	Line%20one%0ALine%20two

In Shortcuts, use the URL Encode action before Open URL.

In JavaScript:

encodeURIComponent('Call Sam & book flights');
// Call%20Sam%20%26%20book%20flights

From Terminal:

python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' 'Call Sam & book flights'

tip

Encode only the parameter value, not the whole URL. For example, encode Call Sam & book flights, then place the result after task=.

Quick Examples

Create a task in the Inbox:

twodo://x-callback-url/add?task=Buy%20milk&forlist=Inbox

Create a task with a note, due date, due time, tags, and a priority:

twodo://x-callback-url/add?task=Submit%20expenses&note=Attach%20receipts&forlist=Work&due=2026-05-08&duetime=17:00&tags=finance%2Cadmin&priority=2

Create a checklist from multiple lines:

twodo://x-callback-url/add?task=Trip%20prep&type=2&subtasks=Book%20flights%0AReserve%20hotel%0APack%20passport

Open the Today Focus List:

twodo://x-callback-url/showtoday

Search for tasks containing invoice:

twodo://x-callback-url/search?text=invoice

Public Actions

These are the public x-callback-url actions that are useful for user automation in 2Do for Mac.

Action	Purpose
add	Create a task, project, or checklist.
addnewtask	Open the new-task interface.
paste	Create tasks from plain text.
search	Search tasks.
showall	Open the All Focus List.
showtoday	Open the Today Focus List.
showstarred	Open the Starred Focus List.
showscheduled	Open the Scheduled Focus List.
showlist	Open a list by name.
showtask	Open a task by UID.
completetasks	Mark one or more tasks complete by UID.
gettaskid	Find a project UID by title and list.
launch	Bring 2Do to the front.

Creating Tasks with add

Use add when you want a URL to create a task directly.

twodo://x-callback-url/add?task=Call%20Sam&forlist=Work

Basic Parameters

Parameter	Description
task	Task title. If omitted, 2Do uses New Task.
note	Notes for the task.
forlist	Destination list name. If omitted, 2Do uses the default or last-used list.
forparentname	Parent project or checklist title. Use this with forlist so 2Do can find the right parent.
forparenttask	Parent project or checklist UID. Use this when your automation already knows the parent UID.
type	0 for a regular task, 1 for a project, 2 for a checklist.
ignoredefaults	1 tells 2Do not to apply default list/date/alert settings while creating the task.
edit	1 creates the task, then opens it for editing.
usequickentry	1 opens Quick Entry with the provided details instead of saving the task immediately.
saveinclipboard	1 copies the new task UID to the clipboard after the task is created.

note

Use addnewtask when you only want to open the new-task interface. Use add?usequickentry=1 when you want Quick Entry pre-filled with URL parameters.

Dates, Times, and Repeat

Parameter	Description
due	Due date. Use yyyy-MM-dd, a supported date phrase such as tomorrow, or a number of days from today (0 = today, 1 = tomorrow).
duetime	Due time, such as 17:00 or 5pm. This is applied when a due date is supplied.
start	Start date/time. Use yyyy-MM-dd HH:mm or a number of days from today.
repeat	Repeat preset: 1 daily, 2 weekly, 3 every two weeks, 4 monthly. A due date or start date is required.

Examples:

twodo://x-callback-url/add?task=Pay%20rent&due=2026-06-01&duetime=09:00&repeat=4

twodo://x-callback-url/add?task=Review%20agenda&start=2026-05-08%2009:00

Organization and Details

Parameter	Description
tags	Comma-separated tag names. Existing tags are reused, and new tags can be created.
locations	Comma-separated location names. 2Do matches existing locations.
subtasks	Newline-separated sub-task titles. If the parent is a regular task, it becomes a checklist.
priority	0 none, 1 low, 2 medium, 3 high.
starred	1, true, or yes stars the task.
action	Adds an Action. Use call:, message:, url:, visit:, or google: followed by the target value.
picture	Base64-encoded image data.
audio	Base64-encoded audio data.

Action examples:

twodo://x-callback-url/add?task=Call%20Alex&action=call%3A%2B15551234567

twodo://x-callback-url/add?task=Open%20project%20brief&action=url%3Ahttps%3A%2F%2Fexample.com%2Fbrief

Clipboard Values

For automation shortcuts, these parameters can use (clipboard) as their value:

Parameter	Clipboard behavior
task	Uses the clipboard as the task title.
note	Uses the clipboard as the notes body.
tags	Uses the clipboard as the comma-separated tag list.
locations	Uses the clipboard as the comma-separated location list.
subtasks	Uses the clipboard as the newline-separated sub-task list.

Example:

twodo://x-callback-url/add?task=(clipboard)&forlist=Inbox

Opening Lists and Focus Lists

Open a normal list by name:

twodo://x-callback-url/showlist?name=Work

Open built-in Focus Lists:

twodo://x-callback-url/showall
twodo://x-callback-url/showtoday
twodo://x-callback-url/showstarred
twodo://x-callback-url/showscheduled

tip

There is no separate showinbox action. Use showlist?name=Inbox if your Inbox list is named Inbox.

Searching

Use search with the text parameter:

twodo://x-callback-url/search?text=invoice

You can also search for clipboard text:

twodo://x-callback-url/search?text=(clipboard)

Pasting Multiple Tasks

Use paste when you already have a block of plain text and want 2Do to create tasks from it. 2Do treats non-empty lines as separate tasks.

Parameter	Description
text	Plain text to paste. Use %0A for line breaks.
forlist	Optional destination list name.
inproject	Optional project/checklist title inside forlist.

Create three Inbox tasks:

twodo://x-callback-url/paste?forlist=Inbox&text=Buy%20milk%0ACall%20Sam%0ABook%20flights

Paste into a project:

twodo://x-callback-url/paste?forlist=Work&inproject=Website%20Launch&text=Write%20copy%0AReview%20screenshots

Opening a Task by UID

Use showtask when your automation already knows the task UID:

twodo://x-callback-url/showtask?uid=<task-uid>

The easiest way to get a newly created task UID is to call add with saveinclipboard=1 or with an x-success callback.

Completing Tasks by UID

2Do for Mac supports marking one or more tasks complete by UID:

twodo://x-callback-url/completetasks?uids=<uid1>,<uid2>

Use commas between multiple UIDs.

note

2Do iOS does not include the completetasks URL action. Use this action only in Mac-specific workflows.

Looking Up a Project UID

Use gettaskid to find a project or checklist by title inside a list.

twodo://x-callback-url/gettaskid?task=Website%20Launch&forlist=Work

Parameter	Description
task	Project or checklist title.
forlist	List name containing that project or checklist.
saveinclipboard	1 copies the found UID to the clipboard.

On success, the callback receives a uid parameter.

x-callback-url Callbacks

Every action can use the standard x-callback-url parameters:

Parameter	Description
x-success	URL to open after success.
x-error	URL to open after an error.
x-cancel	URL to open if the action is cancelled.
x-source	Optional calling app name.

The add action returns the new task UID in an add parameter:

twodo://x-callback-url/add?task=Draft%20proposal&x-success=shortcuts%3A%2F%2Fx-callback-url%2Frun-shortcut%3Fname%3DTask%2520Created

The gettaskid action returns the found project/checklist UID in a uid parameter.

Not Available as Public Actions

For clarity, these are not public automation endpoints:

Endpoint	Use this instead
quickEntry	Use addnewtask, or add?usequickentry=1 on Mac.
showinbox	Use showlist?name=Inbox.
Sync sign-in callback URLs	These are handled internally during account authorization and are not part of the public URL scheme.
Widget picker callbacks	These are used by 2Do's widgets and are not needed for normal automation.

If you need a public action that is not listed here, contact us.