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)

Did this answer your question?