Action URLs in Today follow the x-url-callback specification offering a great way to perform various actions in Today and retrieve usefull habit data using other apps in iOS like Worfklow or Launch Center Pro.
Today URL Scheme actions look like this:
today://x-callback-url/[action]?[action parameters]
Where can I find all the available URL actions in Today?
All URL actions can be found in Today by opening the "Action URLs" section in Today's settings. Today's actions are currently split into categories:
Global actions
These actions can be performed across habits like getting a list of habits due for Today.
Habit specific actions
These actions can be applied to each habit created in Today. Each habit has its own autogenerated identifier that you can use as a parameter to specify which habit you want a particular action to.
Below is a detailed specification of all actions currently available in Today. We are planning to add more actions in the future and there might be changes in the way we handle existing actions so we strongly recommend that you refer to this article as often as possible.
Habit specific actions
/open-habitOpen Today and jump to that habit and retrieve information about that habit.
Example:
today://x-callback-url/open-habit?id=p14Parameters
id (Required) The unique identifier for each habit
x-success
id: The habit’s unique identifier
title: The habit’s title
total: Total check-ins for the habit (all-time)
total-today: Check-ins made today
remaining-today: Check-ins remaining for today
x-error
errorCode: The identifier of the error
errorMessage: The description of the error
Possible errors:
Habit not found (error id: 1)
The operation could not be completed (error id: 2)
/checkinPerform a check-in on a specific habit. If the habit is already checked in no action will be performed. If the habit has multiple daily check-ins, a new check-in will be performed each time the URL is called.
Example:
today://x-callback-url/check-in?id=p14Parameters
id (Required) The unique identifier for each habit
x-success
id: The habit’s unique identifier
title: The habit’s title
total: Total check-ins for the habit (all-time)
total-today: Check-ins made today
remaining-today: Check-ins remaining for today
x-error
errorCode: The identifier of the error
errorMessage: The description of the error
Possible errors:
Habit not found (error id: 1)
The operation could not be completed (error id: 2)
/revoke-checkinRevoke a check-in on a specific habit. If the habit doesn't have any check-ins, no action will be performed. If the habit has multiple daily check-ins, each call to this action will remove a single check-in.
Example:
today://x-callback-url/revoke-checkin?id=p14Parameters
id (Required) The unique identifier for each habit
x-success
id: The habit’s unique identifier
title: The habit’s title
total: Total check-ins for the habit (all-time)
total-today: Check-ins made today
remaining-today: Check-ins remaining for today
x-error
errorCode: The identifier of the error
errorMessage: The description of the error
Possible errors:
Habit not found (error id: 1)
The operation could not be completed (error id: 2)
Global actions
/show-habitsOpens Today's and jumps to the habits overview screen to display the habits specified by the filter parameter.
Example:
today://x-callback-url/show-habits?filter=allParameters
filter (Optional) Can be either "today" or "all" - Default: "today"Setting the filter value to "today" will show and return data for all habits due for today and "all" will show and return data for the all habits available in Today.
x-success
habit-titles: Dictionary containing the titles of the returned habits
habit-ids: Dictionary containing the returned habit ids
total: The sum of the check-ins for today for all returned habits
remaining: The sum of remaining check-ins for all returned habits
x-error
errorCode: The identifier of the error
errorMessage: The description of the error
Possible errors:
The operation could not be completed (error id: 2)