Things URL Scheme

Last Updated: Feb 13, 2018 02:57PM CET

The URL scheme lets pro users and developers of other apps send commands to Things. This page explains how it works.

Here are some examples of commands that Things understands:

  • Create a new to-do named “Buy milk”.
  • Show the Today list.
  • Show all to-dos tagged with “Errand”.
  • Search all to-dos for “shipping address”.

There's also a powerful JSON-based command that lets you create entire projects, together with all their notes, headings, and to-dos.

Link Builder

You can find the full documentation for each supported command further below. If you want to jump right in, here's a little link builder tool to get you started. Simply fill out some of the fields and the corresponding link will be created for you on the fly. Enjoy!

add

things:///...
? / ?
? or ?
?
?
?
?
?
?
?
? / ?
?

add-project

things:///...
?
? or ?
?
?
?
?
?
? / ?
?

show

things:///...
?
?
?
things:///...
?

add-json

things:///...
?
?

Overview

Commands are sent to Things by constructing special URL links of the form:

things:///commandName?
    parameter1=value1&
    parameter2=value2&
    ...

Opening these links will launch the app and execute the command. Here's how you would tell Things to create a to-do:

things:///add?
    title=Buy%20milk&
    notes=High%20fat

Support for x-callback-url

All commands support the x-callback-url convention by calling the provided x-success, x-error or x-cancel callbacks as appropriate. Many commands return parameters to the x-success callback.

Getting IDs

Some commands require you to provide IDs of to-dos or lists. Here's how you can retrieve them in Things.

To get the ID of a to-do:

  • On the Mac, control-click on the to-do and choose Share > Copy Link.
  • On iOS, tap the to-do to open it and in the toolbar at the bottom, tap > Share > Copy Link.

To get the ID of a list:

  • On the Mac, control-click on the list in the sidebar and choose Share > Copy Link.
  • On iOS, navigate into the list and at the top right of the screen, tap > Share > Copy Link.

Data Types

The commands use the following data types for their parameters:

string
Percent encoded. Maximum un-encoded string length: 4,000 characters unless otherwise specified.
date string
String. Either today, tomorrow or a date string of the form yyyy-mm-dd. E.g. 2017-09-29. Things will also attempt to interpret natural language dates such as in 3 days or next tuesday. These must be provided in English, regardless of the user's device language.
time string
A string describing a time in the local time zone. E.g. 9:30PM or 21:30.
date time string
A date string followed by the @ symbol and then followed by a time string. E.g. 2018-02-25@14:00.
boolean
A boolean value. Either true or false.
JSON string
A string in JSON format. See http://www.json.org/ for more details.

Enabling the URL Scheme

The first time you execute a command via the URL scheme, Things will ask you if you want to enable this feature. Simply answer with Enable.

You can later change this in Things' settings:

  • On the Mac, go to Things > Preferences > General.
  • On iOS, go to Settings > General > Advanced.

add command

Add a to-do. For example, create a to-do in the inbox:

things:///add?
    title=Book%20flights

Create a to-do with a tag and notes set to start this evening:

things:///add?
    title=Buy%20milk&
    notes=Low%20fat.&
    when=evening&
    tags=Errand

Create several to-dos and add them to the Shopping project:

things:///add?
    titles=Milk%0aBeer%0aCheese&
    list=Shopping

Create and schedule a to-do for next Monday in the Health area (with ID of 3052219D-8039-43D0-8654-AE1E20BE4F56):

things:///add?
    title=Call%20doctor&
    when=next%20monday&
    list-id=3052219D-8039-43D0-8654-AE1E20BE4F56

Create a to-do in the “This Evening” list with a reminder at 6PM:

things:///add?
    title=Collect%20dry%20cleaning&
    when=evening@6pm

Parameters

All parameters are optional. If neither the when nor list-id are specified, the to-do will be added to the inbox.

title
String. The title of the to-do to add. Ignored if titles is also specified.
titles
String separated by new lines (encoded to %0a). Use instead of title to create multiple to-dos. Takes priority over title and show-quick-entry. The other parameters are applied to all the created to-dos.
notes
String. The text to use for the notes field of the to-do. Maximum unencoded length: 10,000 characters.
when
String. Possible values: today, tomorrow, evening, someday, a date string, or a date time string. Using a date time string adds a reminder for that time. The time component is ignored if someday is specified.
deadline
Date string. The deadline to apply to the to-do.
tags
Comma separated strings corresponding to the titles of tags. Does not apply a tag if the specified tag doesn’t exist.
checklist-items
String separated by new lines (encoded to %0a). Checklist items to add to the to-do (maximum of 100).
list-id
String. The ID of a project or area to add to. Takes precedence over list.
list
String. The title of a project or area to add to. Ignored if list-id is present.
heading
String. The title of a heading within a project to add to. Ignored if a project is not specified.
completed
Boolean. Whether or not the to-do should be set to complete. Default: false. Ignored if canceled is also set to true.
canceled
Boolean. Whether or not the to-do should be set to canceled. Default: false. Takes priority over completed.
show-quick-entry
Boolean. Whether or not to show the quick entry dialog (populated with the provided data) instead of adding a new to-do. Ignored if titles is specified. Default: false.
reveal
Boolean. Whether or not to navigate to and show the newly created to-do. If multiple to-dos have been created, the first one will be shown. Ignored if show-quick-entry is also set to true. Default: false.

Return parameters on x-success

x-things-id
Comma separated string. The IDs of the to-dos created.

add-project command

Add a project. For example, create a project to build a treehouse set to start today:

things:///add-project?
    title=Build%20treehouse&
    when=today

Create a project inside the Family area:

things:///add-project?
    title=Plan%20Birthday%20Party&
    area=Family

Create a project inside the Finance area (with ID of F00A4075-0CA6-4A7F-88C6-CC8B4F1712FC) with a deadline of December 31:

things:///add-project?
    title=Submit%20Tax&
    deadline=December%2031&
    area-id=F00A4075-0CA6-4A7F-88C6-CC8B4F1712FC

Parameters

All parameters are optional.

title
String. The title of the project.
notes
String. The text to use for the notes field of the project. Maximum unencoded length: 10,000 characters.
when
String. Possible values: today, tomorrow, evening, someday, a date string, or a date time string. Using a date time string adds a reminder for that time. The time component is ignored if someday is specified.
deadline
Date string. The deadline to apply to the project.
tags
Comma separated strings corresponding to the titles of tags. Does not apply a tag if the specified tag doesn’t exist.
area-id
String. The ID of an area to add to. Takes precedence over area.
area
String. The title of an area to add to. Ignored if area-id is present.
to-dos
String separated by new lines (encoded to %0a). Titles of to-dos to create inside the project.
completed
Boolean. Whether or not the project should be set to complete. Default: false. Ignored if canceled is also set to true. Will set all child to-dos to be completed.
canceled
Boolean. Whether or not the project should be set to canceled. Default: false. Takes priority over completed. Will set all child to-dos to be canceled.
reveal
Boolean. Whether or not to navigate into the newly created project. Default: false.

Return parameters on x-success

x-things-id
string. The ID of the project created.

show command

Navigate to and show an area, project, tag or to-do, or one of the built-in lists, optionally filtering by one or more tags.

Navigate to the Today list:

things:///show?
    id=today

Show to-do with ID 8796CC16E-92FA-4809-9A26-36194985E87B:

things:///show?
    id=8796CC16E-92FA-4809-9A26-36194985E87B

Navigate into project with ID 9096CC16E-92FA-4809-9A26-36194985E44A:

things:///show?
    id=9096CC16E-92FA-4809-9A26-36194985E44A

Show project with title “Vacation”:

things:///show?
    query=vacation

Show project with title “Vacation”, filtering by the “Errand” tag:

things:///show?
    query=vacation&
    filter=errand

Parameters

Either id or query must be specified; filter is optional.

id
String. The ID of an area, project, tag or to-do to show; or one of the following built-in list IDs: inbox, today, anytime, upcoming, someday, logbook. Takes precedence over query.
query
String. The name of an area, project, tag or a built-in list to show. This is equivalent to entering the query text in to the quick find within Things and selecting the first result. Ignored if id is also set. Note: task cannot be shown using the query parameter; use the id parameter or the search command instead.
filter
String. Comma separated strings corresponding to the titles of tags that the list should be filtered by.

Return parameters on x-success

none

search command

Invoke and show the search screen. For example, search for the text “vacation”:

things:///search?
    query=vacation

Show the search screen without searching for anything:

things:///search

Parameters

All parameters are optional.

query
String. The search query.

Return parameters on x-success

none

version command

The version of the Things app and URL scheme.

things:///version

Parameters

none

Return parameters on x-success

x-things-scheme-version
String. The version of the Things URL scheme.
x-things-client-version
String. The build number of the app.

add-json command (for Developers)

Things also has an advanced, JSON-based add command that allows more control over the projects and to-dos imported into Things. This command is intended to be used by app developers or other people familiar with scripting or programming.

We’ve created a set of Swift helper classes that you can use to more easily generate the JSON needed for this command. Get the code from the Things JSON Coder GitHub repository.

Example:

things:///add-json?data=
  [
    {
      "type": "project",
      "attributes": {
        "title": "Go Shopping",
        "items": [
          {
            "type": "to-do",
            "attributes": {
              "title": "Bread"
            }
          },
          {
            "type": "to-do",
            "attributes": {
              "title": "Milk"
            }
          }
        ]
      }
    }
  ]

Parameters

data
JSON string. The JSON should be an array containing to-do and project objects (see below).
reveal
Boolean. Whether or not to navigate to and show the newly created to-do or project. If multiple items have been created, the first one will be shown. Default: false.

Return parameters on x-success

x-things-ids
JSON string. An array of IDs of the to-dos and projects created that were specified in the top level JSON array. The IDs of the to-dos created inside projects are not returned.

Describing Things objects in JSON

Each object consists of a type and a dictionary of attributes. The type and attributes must be included but all attributes themselves are optional.

To-do

{
  "type": "to-do",
  "attributes": {
    "title": "Milk"
  }
}
  • type is to-do.
  • attributes:
    • title - string. The title of the to-do.
    • notes - string. The text to use for the notes field of the to-do. Maximum length: 10,000 characters.
    • when - string. Possible values: today, tomorrow, evening, someday, a date string, or a date time string. Using a date time string adds a reminder for that time. The time component is ignored if someday is specified.
    • deadline - date string. The deadline to apply to the to-do.
    • tags - array of strings corresponding to the titles of tags. Does not apply a tag if a tag with the specified title doesn’t exist.
    • checklist-items - array of checklist-item objects (maximum of 100).
    • list-id - string. The ID of a project or area to add to. Takes precedence over list. Ignored if the to-do is specified inside the items array of a project object.
    • list - string. The title of a project or area to add to. Ignored if list-id is present, or if the to-do is specified inside the items array of a project object.
    • heading - string. The title of a heading within a project to add to. Ignored if a project is not specified, or if the to-do is specified inside the items array of a project object.
    • completed - boolean. Whether or not the to-do should be set to complete. Default: false. Ignored if canceled is also set to true.
    • canceled - boolean. Whether or not the to-do should be set to canceled. Default: false. Takes priority over completed.

Project

{
  "type": "project",
  "attributes": {
    "title": "Go Shopping",
    "items": [
      {
        "type": "to-do",
        "attributes": {
          "title": "Bread"
        }
      }
    ]
  }
}
  • type is project.
  • attributes:
    • title - string. The title of the project.
    • notes - string. The text to use for the notes field (maximum length: 10,000 characters).
    • when - string. Possible values: today, tomorrow, evening, someday, a date string, or a date time string. Using a date time string adds a reminder for that time. The time component is ignored if someday is specified.
    • deadline - date string. The deadline to apply.
    • tags - array of strings corresponding to the titles of tags. Does not apply a tag if a tag with the specified title doesn’t exist.
    • area-id - string. The ID of an area to add to. Takes precedence over area.
    • area - string. The title of an area to add to. Ignored if area-id is present.
    • items array of to-do or heading objects.
    • completed - boolean. Whether or not the project should be set to complete. Default: false. Ignored unless all child to-dos are completed or canceled.
    • canceled - boolean. Whether or not the project should be set to canceled. Default: false. Takes priority over completed. Ignored unless all child to-dos are completed or canceled.

Heading

{
  "type": "heading",
  "attributes": {
    "title": "Sights"
  }
}
  • type is heading.
  • attributes:
    • title - string. The title of the heading.
    • archived - boolean. Whether or not the heading is archived. Default: false. Ignored unless all to-dos under the heading are completed or canceled.

Checklist Item

{
  "type": "checklist-item",
  "attributes": {
    "title": "Hotels",
    "completed": true
  }
}
  • type is checklist-item.
  • attributes:
    • title - string. The title of the checklist item.
    • completed - boolean. Whether or not the checklist item should be set to complete. Default: false. Ignored if canceled is also set to true.
    • canceled - boolean. Whether or not the checklist item should be set to canceled. Default: false. Takes priority over completed.

JSON Example

This example is not URL encoded for clarity.

things:///add-json?data=
  [
    {
      "type": "project",
      "attributes": {
        "title": "Go Shopping",
        "items": [
          {
            "type": "to-do",
            "attributes": {
              "title": "Bread"
            }
          },
          {
            "type": "to-do",
            "attributes": {
              "title": "Milk"
            }
          }
        ]
      }
    },
    {
      "type": "project",
      "attributes": {
        "title": "Vacation in Rome",
        "notes": "Some time in August.",
        "area": "Family",
        "items": [
          {
            "type": "to-do",
            "attributes": {
              "title": "Ask Sarah for travel guide"
            }
          },
          {
            "type": "to-do",
            "attributes": {
              "title": "Add dates to calendar"
            }
          },
          {
            "type": "heading",
            "attributes": {
              "title": "Sights"
            }
          },
          {
            "type": "to-do",
            "attributes": {
              "title": "Vatican City"
            }
          },
          {
            "type": "to-do",
            "attributes": {
              "title": "The Colosseum",
              "notes": "12€"
            }
          },
          {
            "type": "heading",
            "attributes": {
              "title": "Planning"
            }
          },
          {
            "type": "to-do",
            "attributes": {
              "title": "Call Paolo",
              "completed": true
            }
          },
          {
            "type": "to-do",
            "attributes": {
              "title": "Book flights",
              "when": "today"
            }
          },
          {
            "type": "to-do",
            "attributes": {
              "title": "Research",
              "checklist-items": [
                {
                  "type": "checklist-item",
                  "attributes": {
                    "title": "Hotels",
                    "completed": true
                  }
                },
                {
                  "type": "checklist-item",
                  "attributes": {
                    "title": "Transport from airport"
                  }
                }
              ]
            }
          }
        ]
      }
    },
    {
      "type": "to-do",
      "attributes": {
        "title": "Pick up dry cleaning",
        "when": "evening",
        "tags": [
          "Errand"
        ]
      }
    },
    {
      "type": "to-do",
      "attributes": {
        "title": "Submit report",
        "deadline": "2018-02-01",
        "list": "Work"
      }
    }
  ]

URL Encoded Example

All of the above JSON examples must have the white space removed and then be URL encoded before they can be used. For example:

things:///add-json?data=
  [
    {
      "type": "to-do",
      "attributes": {
        "title": "Buy milk"
      }
    }
  ]

After removing white space:

things:///add-json?data=[{"type":"to-do","attributes":{"title":"Buy milk"}}]

After URL encoding:

things:///add-json?data=%5B%7B%22type%22:%22to-do%22,%22attributes%22:%7B%22title%22:%22Buy%20milk%22%7D%7D%5D



Didn’t find what you were looking for?

https://cdn.desk.com/
culturedcode
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
Invalid characters found
/customer/en/portal/articles/autocomplete