Action URLs Documentation

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-habit
Open Today and jump to that habit and retrieve information about that habit.

Example:
today://x-callback-url/open-habit?id=p14

Parameters

  • 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)

/checkin
Perform 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=p14

Parameters

  • 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-checkin
Revoke 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=p14

Parameters

  • 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-habits
Opens 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=all

Parameters

  • 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)


If you are experiencing any issues with the actions above or you want to suggest a new action contact our support team at https://todaysupport.uservoice.com






















Feedback and Knowledge Base