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'
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¬e=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. |
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: (or mail:), 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
There is no separate showinbox action. Use showlist?name=Inbox if your Inbox list is named Inbox. Note that showlist?name= matches the list name case-sensitively, unlike add?forlist=.
Searching
Use search with the text parameter:
twodo://x-callback-url/search?text=invoice
((clipboard) substitution works only on the add parameters listed above, because search?text= takes the literal text you pass it.)
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.
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.