Things3 provides a URL Scheme as the primary interface for external programs to interact with Things. This is the only officially supported write method.

Current URL Scheme version: 2

1. Things 3 installed and running on macOS
2. Things → Settings → General → Enable Things URLs
3. Modification operations (update) require an auth-token: Things → Settings → General → Things URLs → Manage

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

All commands support the x-callback-url protocol:

• x-success: success callback URL
• x-error: error callback URL
• x-cancel: cancel callback URL

# Open directly on macOS
open "things:///add?title=Buy%20milk"

# Run in background (without switching to the Things window)
open -g "things:///add?title=Buy%20milk"

# Via osascript
osascript -e 'open location "things:///add?title=Buy%20milk"'

1. Empty parameter clears value: Including = without a value (e.g., deadline=) clears that field. This is a general rule that applies to all clearable fields (deadline, when, tags, etc.), not just deadline.
2. Default to Inbox: When the add command does not specify when or list-id, the to-do goes to the Inbox by default.
3. Tags must already exist: The tags / add-tags parameters can only reference existing tags. Tag names that do not exist will be silently ignored and will not be created automatically.
4. ID takes priority: list-id takes priority over list, heading-id takes priority over heading, area-id takes priority over area.
5. canceled takes priority: When both completed and canceled are set, canceled takes effect.
6. Bidirectional reopen: Setting completed=false on a canceled to-do marks it as incomplete; conversely, setting canceled=false on a completed to-do also marks it as incomplete.
7. Rate limit: Maximum 250 add operations within 10 seconds.
8. Unicode support: Titles, notes, and other fields support Unicode characters; URL encoding is required.

things:///add?title=...&notes=...&when=...

use-clipboard behavior details:

• replace-title: Clipboard content replaces the title; if the clipboard has multiple lines, the first line becomes the title, and the remaining lines overflow into notes, replacing notes
• replace-notes: Clipboard content replaces the notes
• replace-checklist-items: Clipboard content replaces the checklist; each line creates one checklist item

Returns: x-things-id — comma-separated UUIDs of created to-dos

Examples:

things:///add?title=Buy%20milk&notes=Low%20fat&when=evening&tags=Errand
things:///add?titles=Milk%0aBeer%0aCheese&list=Shopping
things:///add?title=Call%20doctor&when=next%20monday&list-id=TryhwrjdiHEXfjgNtw81yt
things:///add?title=Collect%20dry%20cleaning&when=evening@6pm

things:///add-project?title=...&to-dos=...

Returns: x-things-id — project UUID

Examples:

things:///add-project?title=Plan%20Birthday%20Party&area=Family
things:///add-project?title=Submit%20Tax&deadline=December%2031&area-id=Lg8UqVPXo2SbJNiBpDBBQ

things:///update?auth-token=...&id=...&title=...

Required: id + auth-token

heading behavior in update: If the to-do is not in a project that has that heading, the parameter is ignored. You can specify list/list-id at the same time to first move to the target project and then set the heading.

Limitations:

• Cannot modify when/deadline/completed/completion-date of repeating tasks
• Cannot duplicate repeating tasks

Returns: x-things-id — UUID of the updated to-do

Examples:

things:///update?auth-token=TOKEN&id=SyJEz273ceSkabUbciM73A&when=today
things:///update?auth-token=TOKEN&id=SyJEz273ceSkabUbciM73A&append-notes=Details
things:///update?auth-token=TOKEN&id=SyJEz273ceSkabUbciM73A&deadline=

things:///update-project?auth-token=...&id=...

Required: id + auth-token

Differences from update:

• No checklist-related parameters
• No heading / list related parameters (projects cannot be nested inside other projects)
• Has area / area-id parameters

Prerequisites for completing/canceling: Setting completed=true or canceled=true requires all sub to-dos to be completed or canceled, and all sub headings to be archived. Otherwise the operation is ignored.

Limitations:

• Cannot modify when/deadline/completed/completion-date of repeating projects
• Cannot duplicate repeating projects
• Cannot add to-dos to a project via this command (use the list-id parameter of the add command instead)
• Cannot manage headings within a project

Returns: x-things-id — UUID of the updated project

Examples:

things:///update-project?auth-token=TOKEN&id=Jvj7EW1fLoScPhaw2JomCT&when=tomorrow
things:///update-project?auth-token=TOKEN&id=Jvj7EW1fLoScPhaw2JomCT&add-tags=Important
things:///update-project?auth-token=TOKEN&id=Jvj7EW1fLoScPhaw2JomCT&prepend-notes=SFO%20to%20JFK.
things:///update-project?auth-token=TOKEN&id=Jvj7EW1fLoScPhaw2JomCT&deadline=

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

Built-in list IDs: inbox, today, anytime, upcoming, someday, logbook, tomorrow, deadlines, repeating, all-projects, logged-projects

query limitations: query can search by area, project, or tag name, but cannot search for to-dos. To navigate to a specific to-do, you must use the id parameter or the search command.

Types supported by id: Can pass the UUID of a to-do, project, area, or tag.

things:///search?query=vacation

things:///version

Returns: x-things-scheme-version (currently 2) + x-things-client-version (app build number)

This is the most powerful command, supporting the creation/modification of multiple complex objects in a single call.

things:///json?data=<URL-encoded JSON array>&auth-token=TOKEN&reveal=true

Returns: x-things-ids — top-level UUIDs in JSON array format

{
  "type": "to-do" | "project" | "heading" | "checklist-item",
  "operation": "create" | "update",
  "id": "required only for update",
  "attributes": { ... }
}

{
  "title": "Title",
  "notes": "Notes",
  "when": "today",
  "deadline": "2026-12-31",
  "tags": ["Tag1", "Tag2"],
  "checklist-items": [
    {"type": "checklist-item", "attributes": {"title": "Sub-item", "completed": false}}
  ],
  "list-id": "project/area UUID",
  "list": "project/area name",
  "heading-id": "heading UUID",
  "heading": "heading name",
  "completed": false,
  "canceled": false,
  "creation-date": "2026-03-10T14:30:00Z",
  "completion-date": "2026-03-10T14:30:00Z"
}

Supports an items array when creating (for nesting to-do and heading objects):

{
  "title": "Project name",
  "notes": "Notes",
  "when": "today",
  "deadline": "2026-12-31",
  "tags": ["Tag1"],
  "area-id": "area UUID",
  "area": "area name",
  "completed": false,
  "canceled": false,
  "creation-date": "...",
  "completion-date": "...",
  "items": [
    {"type": "to-do", "attributes": {"title": "Task 1"}},
    {"type": "heading", "attributes": {"title": "Phase 2"}},
    {"type": "to-do", "attributes": {"title": "Task 2"}}
  ]
}

prepend-notes, append-notes, add-tags (same as to-do update)

[
  {
    "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": "heading", "attributes": {"title": "Sights"}},
        {"type": "to-do", "attributes": {"title": "Vatican City"}},
        {"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",
    "operation": "update",
    "id": "Di9deEJeUkVZaDEdbnzQZw",
    "attributes": {"deadline": "today"}
  }
]

Use the json command instead.

• To-do ID: Control-click to-do → Share → Copy Link (Mac); Tap to-do → Toolbar → Share → Copy Link (iOS)
• Project/List ID: Control-click the list in the sidebar → Share → Copy Link
• Tag ID: Same as above, control-click the tag
• Via database: Read from the uuid field of the TMTask / TMArea / TMTag tables
• Auth Token: SELECT uriSchemeAuthenticationToken FROM TMSettings WHERE uuid = 'RhAzEf6qDxCD5PmnZVtBZR'

• ThingsJSONCoder: Official Swift helper class from Cultured Code for generating JSON command payloads — https://github.com/culturedcode/ThingsJSONCoder