### Add projects using the add-project command

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

Examples of creating projects with specific titles, schedules, areas, and deadlines.

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

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

```URL
things:///add-project?
    title=Submit%20Tax&
    deadline=December%2031&
    area-id=Lg8UqVPXo2SbJNiBpDBBQ
```

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

### Add to-dos using the add command

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

Examples of creating various types of to-dos, including those with tags, notes, schedules, and multiple items.

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

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

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

```URL
things:///add?
    title=Call%20doctor&
    when=next%20monday&
    list-id=TryhwrjdiHEXfjgNtw81yt
```

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

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

### Creating a To-Do via URL

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

Example of using the add command to create a new to-do with a title and notes.

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

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

### GET things:///add-project

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

Adds a new project to the Things application.

```APIDOC
## GET things:///add-project

### Description
Adds a new project to the Things application, optionally within a specific area.

### Method
GET

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

### Parameters
#### Query Parameters
- **title** (string) - Optional - The title of the project.
- **when** (string) - Optional - Start date for the project.
- **area** (string) - Optional - The title of the area to add the project to.
- **area-id** (string) - Optional - The ID of the area to add the project to.
- **deadline** (string) - Optional - Deadline for the project.
```

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

### Update Project Date

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

Sets the start date of a project to tomorrow.

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

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

### JSON Data Structure for Things

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

A raw JSON example representing projects and to-dos. 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"
      }
    }
  ]
```

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

### Getting IDs

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

Instructions on how to retrieve IDs for to-dos and lists in Things.

```APIDOC
## Getting IDs

To retrieve the ID of a to-do:
- **Mac**: Control-click the to-do and choose **Share** → **Copy Link**.
- **iOS**: Tap the to-do, then tap  → **Share** → **Copy Link**.

To retrieve the ID of a list:
- **Mac**: Control-click the list in the sidebar and choose **Share** → **Copy Link**.
- **iOS**: Navigate to the list, tap  → **Share** → **Copy Link**.
```

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

### Update a to-do start date

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

Sets the start date of a specific to-do to today.

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

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

### 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

Initializes a new project with specific properties.

```AppleScript
tell application "Things3"
 set newProject to make new project ¬
  with properties {name:"My Project", notes:"Some notes."}
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 to a project using its ID.

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

```

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

### Command: add-project

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

Creates a new project in Things.

```APIDOC
## POST things:///add-project

### Description
Creates a new project.

### Method
GET

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

### Parameters
#### Query Parameters
- **title** (string) - Required - The title of the project.
- **completed** (boolean) - Optional - Marks the project as completed.
- **canceled** (boolean) - Optional - Marks the project as canceled.
- **reveal** (boolean) - Optional - Reveals the project after creation.
- **notes** (string) - Optional - Notes for the project.
- **when** (date string) - Optional - When the project should be scheduled.
- **deadline** (date string) - Optional - The deadline for the project.
- **tags** (string) - Optional - Comma-separated list of tags to apply.
- **area** (string) - Optional - The name of the area to add the project to.
- **area-id** (string) - Optional - The ID of the area to add the project to.
- **to-dos** (JSON string) - Optional - A JSON string representing to-dos within the project.
- **creation-date** (ISO8601 date time string) - Optional - The creation date of the project.
- **completion-date** (ISO8601 date time string) - Optional - The completion date of the project.
```

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

### Get Items API

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

Retrieves a specified list of items of a given type.

```APIDOC
## POST /get-items

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

### Method
POST

### Endpoint
/get-items

### Parameters
#### Request Body
- **Type** (string) - Required - The type of the items: `To-Do`, `Heading`, `Project`, or `Area`.
- **Items** (array) - Required - A list of item identifiers to retrieve.

### Request Example
```json
{
  "Type": "To-Do",
  "Items": ["item-id-1", "item-id-2"]
}
```

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

#### Response Example
```json
{
  "Items": [
    {
      "ID": "item-id-1",
      "Title": "Example To-Do"
    }
  ]
}
```
```

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

### Show Project by Title

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

To find and display a project by its title, use the 'show' command with the 'query' parameter set to the project's name.

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

```

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

### Command: show

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

Displays a specific to-do, project, or list in Things.

```APIDOC
## GET things:///show

### Description
Displays a specific to-do, project, or list.

### Method
GET

### Endpoint
things:///show

### Parameters
#### Query Parameters
- **id** (string) - Required - The ID of the item to show.
- **query** (string) - Optional - A search query to display.
- **filter** (string) - Optional - A filter to apply when showing items.
```

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

### Get selected to-dos

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

Access 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
```

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

### GET things:///add

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

Adds a new to-do item to the Things inbox or a specified list.

```APIDOC
## GET things:///add

### Description
Adds a new to-do item to the Things database. If no list is specified, the item is added to the inbox.

### Method
GET

### Endpoint
things:///add

### Parameters
#### Query Parameters
- **title** (string) - Optional - The title of the to-do.
- **titles** (string) - Optional - Multiple titles separated by new lines (encoded as %0a).
- **notes** (string) - Optional - Text for the notes field.
- **when** (string) - Optional - Scheduling date or time (e.g., today, tomorrow, evening, date string).
- **deadline** (string) - Optional - Deadline date string.
- **tags** (string) - Optional - Comma separated tag titles.
- **checklist-items** (string) - Optional - Checklist items separated by new lines.
- **use-clipboard** (string) - Optional - Clipboard usage mode (replace-title, replace-notes, replace-checklist-items).
- **list-id** (string) - Optional - ID of a project or area.
- **list** (string) - Optional - Title of a project or area.
- **heading-id** (string) - Optional - ID of a heading within a project.
- **heading** (string) - Optional - Title of a heading within a project.
- **completed** (boolean) - Optional - Set to true to mark as completed.
- **canceled** (boolean) - Optional - Set to true to mark as canceled.
- **show-quick-entry** (boolean) - Optional - Show quick entry dialog instead of adding.
- **reveal** (boolean) - Optional - Navigate to the created to-do.
- **creation-date** (string) - Optional - ISO8601 creation date.
- **completion-date** (string) - Optional - ISO8601 completion date.

### Response
#### Success Response (x-success)
- **x-things-id** (string) - The IDs of the created to-dos.
```

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

### Command: add

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

Creates a new to-do item in Things.

```APIDOC
## POST things:///add

### Description
Creates a new to-do item.

### Method
GET

### Endpoint
things:///add

### Parameters
#### Query Parameters
- **title** (string) - Required - The title of the to-do.
- **titles** (string) - Required - Multiple titles for to-dos.
- **completed** (boolean) - Optional - Marks the to-do as completed.
- **canceled** (boolean) - Optional - Marks the to-do as canceled.
- **show-quick-entry** (boolean) - Optional - Shows the quick entry interface.
- **reveal** (boolean) - Optional - Reveals the to-do after creation.
- **notes** (string) - Optional - Notes for the to-do.
- **checklist-items** (JSON string) - Optional - A JSON string representing checklist items.
- **when** (date string) - Optional - When the to-do should be scheduled.
- **deadline** (date string) - Optional - The deadline for the to-do.
- **tags** (string) - Optional - Comma-separated list of tags to apply.
- **list** (string) - Optional - The name of the list to add the to-do to.
- **list-id** (string) - Optional - The ID of the list to add the to-do to.
- **heading** (string) - Optional - The heading under which to add the to-do.
- **creation-date** (ISO8601 date time string) - Optional - The creation date of the to-do.
- **completion-date** (ISO8601 date time string) - Optional - The completion date of the to-do.
```

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

### Show Items Action

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

Opens Things and displays the provided items.

```APIDOC
## Show Items Action

### Description
Opens Things and shows the items passed into the action. If you pass a single item, it will be shown inside its parent list. If you pass multiple items, they will be shown together in a special list.

### Parameters
#### Request Body
- **Items** (Array) - Required - The items to show in Things.
```

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

### Get Selected Items API

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

Retrieves the items that are currently selected in the active Things window.

```APIDOC
## GET /selected-items

### 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
/selected-items

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

#### Response Example
```json
{
  "Items": [
    {
      "ID": "selected-item-id-1",
      "Title": "Selected Item"
    }
  ]
}
```
```

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

### Get To-Dos

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

Retrieve all to-dos or a specific to-do by name using the Things AppleScript interface.

```APIDOC
## GET to dos

### Description
Access all to-dos in the application or retrieve a specific to-do by its name.

### Request Example
```applescript
tell application "Things3"
 repeat with toDo in to dos
  --- do something with each to-do using the toDo variable
 end repeat
  
  --- get a to-do by name
  set callMom to to do named "Call mom"
end tell
```
```

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

### Manage to-do locations and links

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

Shows how to add file links to notes and organize to-dos into 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
```

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

### Add Projects and To-dos via JSON

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

Use the JSON command to programmatically add projects and to-dos to Things. The data parameter must be a URL-encoded JSON string.

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

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

### Update a To-do Object

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

Example of a JSON object used to update an existing to-do item by its ID.

```json
{
    "type": "to-do",
    "operation": "update",
    "id": "Di9deEJeUkVZaDEdbnzQZw",
    "attributes": {
        "deadline": "today"
    }
}
```

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

### Create Project Action

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

Creates a new project in Things.

```APIDOC
## POST /Create Project

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

### Parameters
#### Request Body
- **Title** (string) - Optional - The desired title of the project.
- **Area** (string) - Optional - The area the project should be added to.
- **Start** (string) - Optional - The desired start of the project: On Date, Anytime, or Someday.
- **Start Date** (string) - Optional - The desired start date of the project.
- **Evening** (boolean) - Optional - Whether or not the project should be planned for the evening.
- **Reminder Time** (string) - Optional - The time when the reminder should fire.
- **Deadline** (string) - Optional - The desired deadline of the project.
- **Tags** (string) - Optional - The desired tags of the project.
- **Status** (string) - Optional - The desired status: Open, Completed, or Canceled.
- **Notes** (string) - Optional - The notes that should be added to the project.
- **Show When Run** (boolean) - Optional - Whether or not the action’s result should be shown in Siri’s UI at runtime.

### Response
#### Success Response (200)
- **Item** (object) - The newly created project.
```

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

### GET things:///version

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

Retrieves the version of the Things app and the version of the URL scheme currently in use.

```APIDOC
## GET things:///version

### Description
Returns the version information for the Things application and its URL scheme.

### Method
GET

### Endpoint
things:///version

### Response
#### Success Response (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.
```

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

### 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
```

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

### Navigate to Today List

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

Use the 'show' command with the 'id' parameter set to 'today' to navigate to the Today list.

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

```

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

### Set to-do properties

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

Demonstrates creating a to-do and updating its properties like name, notes, due date, and tags.

```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
```

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

### Show Quick Entry panel via AppleScript

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

Triggers the Things Quick Entry panel to appear for immediate task creation.

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

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

### Show To-do by ID

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

To display a specific to-do, use the 'show' command with the 'id' parameter set to the to-do's unique identifier.

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

```