### Create a To-Do Example

Source: https://culturedcode.com/things/support/articles/2803573

This example demonstrates how to create a new to-do item with a title and notes using the Things URL scheme.

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

```

--------------------------------

### Add a project to start today

Source: https://culturedcode.com/things/support/articles/2803573

Use this command to create a new project. Specify the project title and when it should start. Parameters must be URL-encoded.

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

--------------------------------

### Update Project Examples

Source: https://culturedcode.com/things/support/articles/2803573

Examples demonstrating how to modify project attributes such as scheduling, tagging, notes, and clearing deadlines using the update-project URL scheme.

```text
things:///update-project?
    id=Jvj7EW1fLoScPhaw2JomCT&
    when=tomorrow
```

```text
things:///update-project?
    id=Jvj7EW1fLoScPhaw2JomCT&
    add-tags=Important
```

```text
things:///update-project?
    id=Jvj7EW1fLoScPhaw2JomCT&
    prepend-notes=SFO%20to%20JFK.
```

```text
things:///update-project?
    id=Jvj7EW1fLoScPhaw2JomCT&
    deadline=
```

--------------------------------

### Show Quick Entry Panel in Things

Source: https://culturedcode.com/things/support/articles/2803572

Reveals the Quick Entry panel in Things, allowing for immediate input of a new to-do. No specific setup is required beyond having Things installed.

```applescript
tell application "Things3"
 show quick entry panel
end tell
```

--------------------------------

### Manage to-do locations and links

Source: https://culturedcode.com/things/support/articles/4562654

Examples of adding file links, placing to-dos in specific lists, projects, or areas.

```AppleScript
tell application "Things3"
 --- add a to-do with a link to a file
 set newToDo to make new to do with properties {name:"Install Xcode", notes: "file:///Users/steve/Downloads/Xcode_26_beta.xip"} ¬
  at beginning of list "Today"

 --- put a to-do in a built-in list
 set newToDo to make new to do with properties {name:"New to-do", due date:current date} ¬
  at beginning of list "Today"

 tell list "Someday"
  set newToDo to make new to do ¬
   with properties {name:"New to-do for someday"}
 end tell

 --- put a to-do in a project
 set newToDo to make new to do ¬
  with properties {name:"Buy milk", due date:current date} ¬
  at beginning of project "Groceries"
    
 tell project "Groceries"
  set newToDo to make new to do ¬
   with properties {name:"Buy bread"}
 end tell

 --- put a to-do in an area
 set newToDo to make new to do ¬
  with properties {name:"New work to-do"} ¬
  at beginning of area "Work"
    
 tell area "Work"
  set newToDo to make new to do with properties {name:"Another work to-do"}
 end tell
end tell
```

--------------------------------

### POST /create-project

Source: https://culturedcode.com/things/support/articles/9596775

Creates a new project with optional start dates, deadlines, and tags.

```APIDOC
## POST /create-project

### Description
Creates a new project. All parameters are optional.

### Parameters
- **Title** (string) - Optional - The desired title of the project.
- **Area** (string) - Optional - The area the project should be added to.
- **Start** (string) - Optional - Start status: On Date, Anytime, or Someday.
- **Start Date** (string) - Optional - Start date.
- **Evening** (boolean) - Optional - Planned for evening.
- **Reminder Time** (string) - Optional - Reminder time.
- **Deadline** (string) - Optional - Deadline date.
- **Tags** (string) - Optional - Tags for the project.
- **Status** (string) - Optional - Open, Completed, or Canceled.
- **Notes** (string) - Optional - Notes for the project.
- **Show When Run** (boolean) - Optional - Show result in Siri UI.
```

--------------------------------

### Get To-Dos from a Project

Source: https://culturedcode.com/things/support/articles/4562654

Retrieves all to-dos associated with a specific project. Replace "Vacation in Rome" with the actual project name.

```applescript
tell application "Things3"
 repeat with romeToDo in to dos of project "Vacation in Rome"
  --- do something with each to-do using the romeToDo variable
 end repeat
end tell
```

--------------------------------

### Navigate to Project by ID

Source: https://culturedcode.com/things/support/articles/2803573

Use the `show` command with the `id` parameter to navigate directly into a project using its ID.

```url
things:///show?
    id=Qi9pM1heCNAZxKREgQrwnJ

```

--------------------------------

### Show Project by Title

Source: https://culturedcode.com/things/support/articles/2803573

Use the `show` command with the `query` parameter to find and display a project by its title.

```url
things:///show?
    query=vacation

```

--------------------------------

### Define Things JSON structure

Source: https://culturedcode.com/things/support/articles/2803573

Example of a complex JSON payload containing projects, to-dos, headings, and checklist items. This example is not URL encoded for clarity.

```json
things:///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": "2026-02-01",
        "list": "Work"
      }
    }
  ]
```

--------------------------------

### Get all tags

Source: https://culturedcode.com/things/support/articles/4562654

Iterates through all available tags.

```AppleScript
tell application "Things3"
  repeat with aTag in tags
    --- do something with each tag using the aTag variable
  end repeat
end tell
```

--------------------------------

### Create a new project

Source: https://culturedcode.com/things/support/articles/4562654

Creates a project with specified properties.

```AppleScript
tell application "Things3"
 set newProject to make new project ¬
  with properties {name:"My Project", notes:"Some notes."}
end tell
```

--------------------------------

### Get Selected Items API

Source: https://culturedcode.com/things/support/articles/9596775

Retrieves the items that are currently selected in Things.

```APIDOC
## GET /items/selected

### Description
Gets the items that are currently selected in Things. If multiple Things windows are open, the last active window is used.

### Method
GET

### Endpoint
/items/selected

### Response
#### Success Response (200)
- **Items** (array) - The selected `Item`s.

#### Response Example
{
  "Items": [
    {
      "ID": "some-uuid",
      "Title": "Selected Item",
      "Type": "To-Do"
    }
  ]
}
```

--------------------------------

### Get Items API

Source: https://culturedcode.com/things/support/articles/9596775

Retrieves a specified list of items of a given type.

```APIDOC
## POST /items/get

### Description
Lets you specify multiple items of a given type, which are then returned by this action.

### Method
POST

### Endpoint
/items/get

### Parameters
#### Request Body
- **Type** (string) - Required - The type of the items: `To-Do`, `Heading`, `Project`, or `Area`.
- **Items** (array) - Required - The items that should be returned by the action.

### Response
#### Success Response (200)
- **Items** (array) - The specified `Item`s.

#### Response Example
{
  "Items": [
    {
      "ID": "some-uuid",
      "Title": "Example Item",
      "Type": "To-Do"
    }
  ]
}
```

--------------------------------

### Command: add-project

Source: https://culturedcode.com/things/support/articles/2803573

Creates a new project in Things.

```APIDOC
## add-project
things:///add-project?
`title`
`completed` or  `canceled`   
`reveal`
`notes`
`when`
`deadline`
`tags`
`area` / `area-id`
`to-dos`
`creation-date`
`completion-date`
```

--------------------------------

### Show Command Parameters

Source: https://culturedcode.com/things/support/articles/2803573

The 'show' command allows displaying specific to-dos or lists by their ID or through a query.

```text
things:///show?
`id`
`query`
`filter`
```

--------------------------------

### Get selected to-dos

Source: https://culturedcode.com/things/support/articles/4562654

Iterate over items currently selected in the user interface.

```AppleScript
tell application "Things3"
 repeat with selectedToDo in selected to dos
  move selectedToDo to list "Today"
 end repeat
end tell
```

--------------------------------

### Show Project by Title with Tag Filter

Source: https://culturedcode.com/things/support/articles/2803573

Use the `show` command with both `query` and `filter` parameters to display a project matching a title and a specific tag.

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

```

--------------------------------

### Add Projects and To-Dos using JSON

Source: https://culturedcode.com/things/support/articles/2803573

This command allows for advanced, JSON-based import of projects and to-dos. It requires a `data` parameter containing a JSON string representing the items to be created or updated. An `auth-token` is needed for update operations.

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


```

--------------------------------

### Tag Management API

Source: https://culturedcode.com/things/support/articles/4562654

APIs for getting, creating, setting, renaming, organizing, and deleting tags.

```APIDOC
## Get items’ tags

### Description
Access items’ `tag names` as strings or objects.

### Method
GET (Implicit)

### Endpoint
N/A (AppleScript command)

### Parameters
None

### Request Example
```applescript
tell application "Things3"
  set aToDo to first to do of list "Inbox"
  
  --- output: a string (e.g. "Home, Mac")
  set tagNames to tag names of aToDo

  --- output: a list of tag objects
  set tagList to tags of aToDo
  repeat with aTag in tagList
    --- do something with each tag using the aTag variable
  end repeat
end tell
```

### Response
#### Success Response (200)
- **tagNames** (string) - Comma-separated string of tag names.
- **tagList** (list) - List of tag objects.

#### Response Example
```json
{
  "tagNames": "Home, Mac",
  "tagList": [
    { "name": "Home" },
    { "name": "Mac" }
  ]
}
```

## Create a new tag

### Description
Use the standard `make` command to create a new tag.

### Method
POST (Implicit)

### Endpoint
N/A (AppleScript command)

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new tag.

### Request Example
```applescript
tell application "Things3"
  set newTag to make new tag with properties {name:"Home"}
end tell
```

### Response
#### Success Response (200)
- **newTag** (object) - The newly created tag object.

#### Response Example
```json
{
  "newTag": {
    "name": "Home"
  }
}
```

## Set tags

### Description
Use the `tag names` property to assign tags to an item.

### Method
PUT (Implicit)

### Endpoint
N/A (AppleScript command)

### Parameters
#### Path Parameters
- **item** (to-do/project) - The item to which tags will be assigned.

#### Request Body
- **tag names** (string) - Required - Comma-separated string of tag names to assign.

### Request Example
```applescript
tell application "Things3"
  set aToDo to first to do of list "Today"
  set tag names of aToDo to "Home, Mac"
end tell
```

### Response
#### Success Response (200)
No explicit response body, operation is confirmed by lack of error.

## Rename a tag

### Description
Set the `name` property of a tag to rename it. The change applies everywhere the tag is used.

### Method
PUT (Implicit)

### Endpoint
N/A (AppleScript command)

### Parameters
#### Path Parameters
- **tag** (tag object) - The tag to rename.

#### Request Body
- **name** (string) - Required - The new name for the tag.

### Request Example
```applescript
tell application "Things3"
  set name of tag "Errands" to "Shopping"
end tell
```

### Response
#### Success Response (200)
No explicit response body, operation is confirmed by lack of error.

## Work with tag hierarchies

### Description
Use the `parent tag` property to establish or modify tag hierarchies.

### Method
PUT (Implicit)

### Endpoint
N/A (AppleScript command)

### Parameters
#### Path Parameters
- **tag** (tag object) - The tag to set the parent for.

#### Request Body
- **parent tag** (tag object) - Optional - The parent tag to assign.

### Request Example
```applescript
tell application "Things3"
  set homeTag to tag "Home"
  set parent tag of homeTag to tag "Places"
end tell
```

### Response
#### Success Response (200)
No explicit response body, operation is confirmed by lack of error.

## Delete tags

### Description
Use the standard `delete` command to remove a tag.

### Method
DELETE

### Endpoint
N/A (AppleScript command)

### Parameters
#### Path Parameters
- **tag** (tag object) - Required - The tag to delete.

### Request Example
```applescript
tell application "Things3"
  set aTag to tag "Errands"
  delete aTag
end tell
```

### Response
#### Success Response (200)
No explicit response body, operation is confirmed by lack of error.
```

--------------------------------

### Get items’ tags

Source: https://culturedcode.com/things/support/articles/4562654

Access tag names as strings or retrieve tag objects for iteration.

```AppleScript
tell application "Things3"
  set aToDo to first to do of list "Inbox"

  --- output: a string (e.g. "Home, Mac")
  set tagNames to tag names of aToDo

  --- output: a list of tag objects
  set tagList to tags of aToDo
  repeat with aTag in tagList
    --- do something with each tag using the aTag variable
  end repeat
end tell
```

--------------------------------

### General Command Structure

Source: https://culturedcode.com/things/support/articles/2803573

Commands are sent to Things by constructing special URL links. Opening these links launches the app and executes the specified command.

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

--------------------------------

### Get To-Dos from Inbox List

Source: https://culturedcode.com/things/support/articles/4562654

Specifically retrieves to-dos that are within the 'Inbox' list. This is useful for processing new or unsorted tasks.

```applescript
tell application "Things3"
 repeat with inboxToDo in to dos of list "Inbox"
  --- do something with each to-do using the inboxToDo variable
 end repeat
end tell
```

--------------------------------

### Set to-do properties

Source: https://culturedcode.com/things/support/articles/4562654

Demonstrates creating a to-do with initial properties and updating individual fields like name, notes, and dates.

```AppleScript
tell application "Things3"
 set newToDo to make new to do ¬
  with properties {name:"New to-do", due date:current date} ¬
  at beginning of list "Anytime"

 set name of newToDo to "This to-do has been renamed!"
 set notes of newToDo to "www.apple.com" & linefeed & "Call Steve for more details."
 set due date of newToDo to (current date) + 7 * days
 set completion date of newToDo to current date
 set tag names of newToDo to "Home, Mac"
end tell
```

--------------------------------

### POST /add-project

Source: https://culturedcode.com/things/support/articles/2803573

Creates a new project in Things with optional parameters for title, notes, scheduling, and tags.

```APIDOC
## POST /add-project

### Description
Creates a new project in Things.

### Method
POST

### Endpoint
things:///add-project

### Parameters
#### Query Parameters
- **title** (string) - Optional - The title of the project.
- **notes** (string) - Optional - The text to use for the notes field of the project (max 10,000 chars).
- **when** (string) - Optional - Scheduling options: today, tomorrow, evening, anytime, someday, date string, or date time string.
- **deadline** (date string) - Optional - The deadline to apply to the project.
- **tags** (string) - Optional - Comma separated strings corresponding to the titles of tags.
- **area-id** (string) - Optional - The ID of an area to add to.
- **area** (string) - Optional - The title of an area to add to.
- **to-dos** (string) - Optional - Titles of to-dos to create inside the project, separated by new lines (encoded to %0a).
- **completed** (boolean) - Optional - Whether the project should be set to complete. Default: false.
- **canceled** (boolean) - Optional - Whether the project should be set to canceled. Default: false.
- **reveal** (boolean) - Optional - Whether to navigate into the newly created project. Default: false.
- **creation-date** (ISO8601 string) - Optional - The date to set as the creation date.
- **completion-date** (ISO8601 string) - Optional - The date to set as the completion date.

### Response
#### Success Response (x-success)
- **x-things-id** (string) - The ID of the project created.
```

--------------------------------

### Update To-Do: Set When to Today

Source: https://culturedcode.com/things/support/articles/2803573

Use the `update` command with the `when` parameter to set a to-do to start today. Requires a valid to-do ID.

```uri
things:///update?
    id=SyJEz273ceSkabUbciM73A&
    when=today
```

--------------------------------

### Command: add

Source: https://culturedcode.com/things/support/articles/2803573

Creates a new to-do item in Things.

```APIDOC
## add
things:///add?
`title` / `titles`
`completed` or  `canceled`   
`show-quick-entry`   
`reveal`
`notes`
`checklist-items`
`when`
`deadline`
`tags`
`list` / `list-id`
`heading`
`creation-date`
`completion-date`
```

--------------------------------

### Access Upcoming To-Dos

Source: https://culturedcode.com/things/support/articles/4562654

Retrieves to-dos from the Upcoming list, which are sorted by start date. This script demonstrates accessing a specific built-in list.

```applescript
tell application "Things3"
 set upcomingToDos to to dos of list "Upcoming"
 repeat with upcomingToDo in upcomingToDos
  --- to-dos are sorted by start date, just like in Things’ UI
 end repeat
end tell
```

--------------------------------

### Getting IDs

Source: https://culturedcode.com/things/support/articles/2803573

Instructions on how to retrieve unique IDs for to-dos and lists within the Things app, which are often required for update and show commands.

```APIDOC
## 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**.
```

--------------------------------

### Command: show

Source: https://culturedcode.com/things/support/articles/2803573

Displays a specific list or to-do in Things.

```APIDOC
## show
things:///show?
`id`
`query`
`filter`
```

--------------------------------

### Add Project

Source: https://culturedcode.com/things/support/articles/2803573

Creates a new project in Things.

```APIDOC
## Add Project

### Description
Creates a new project, optionally including child to-dos and setting project-specific attributes.

### Parameters
#### Request Body
- **title** (String) - Optional - The title of the project.
- **completed** (Boolean) - Optional - Whether the project is complete.
- **canceled** (Boolean) - Optional - Whether the project is canceled.
- **reveal** (Boolean) - Optional - Whether to navigate to the project.
- **notes** (String) - Optional - Notes for the project.
- **when** (String) - Optional - Date or time string.
- **deadline** (Date string) - Optional - Deadline for the project.
- **tags** (String) - Optional - Comma separated tag titles.
- **area** (String) - Optional - Title of an area.
- **area-id** (String) - Optional - ID of an area.
- **to-dos** (String) - Optional - New line separated titles of to-dos to create inside the project.
```

--------------------------------

### Get Things App and URL Scheme Version

Source: https://culturedcode.com/things/support/articles/2803573

Use this command to retrieve the current version of the Things app and its URL scheme. No parameters are required.

```url
things:///version
```