Connect an AI app

Choose your app

Open a guide for the app you use. It shows where to add Plus and how to sign in.

Copy the connector address

Your app's guide tells you where to paste this address. Plus opens a sign-in page when the app connects.

Ask about your tasks

Once connected, try “What's on my Today list?” or “Move buy milk to Tomorrow.” Your AI app chooses the right tool for each request.

Tool reference

Want to check a specific action? Open a tool below to see what it does and which details it needs.

Read tools

• Account statusthings_account_status

  Report the user's plan (status, trial end, whether the tools are available, links to choose a plan or manage the account) and the connection: time zone, read-only mode, whether changes are enabled, whether the connector needs reconnecting or syncing is paused, how much of the data is loaded yet (with an estimate of the time left) and how current it is; also known problems of the service (with the status page) and today's use against the daily fair-use limits. Use it when a tool reports a problem or the user asks about their account; it works even when the plan has ended. Makes no request to Things Cloud.

• Raw data of one itemthings_debug_raw

  Debugging aid: show one object exactly as this server holds it, with every stored field under its Things wire key (days as YYYY-MM-DD, instants as RFC 3339 UTC), plus the most recent raw history events that changed it (up to 20, newest first, from the last 5,000 history entries). Use it only to investigate data that looks wrong in other tools.

  Property	Type	Description
  uuid*	string	id of any object (to-do, project, heading, checklist item, area or tag) or an unambiguous prefix

• Diagnose the connectionthings_diagnose

  Technical health report of the sync with the user's Things Cloud account: cursors, head index, log size, snapshot age, object counts, format flags, sync-blocked and reconnect state, drift events, rate limiter and settings, known problems of the service and today's fair use. Holds no titles, notes, keys or email addresses, so it is safe to share with support. Makes no request to Things Cloud. Use it when data looks wrong or a tool keeps failing.

• Find areasthings_find_areas

  List all areas of responsibility in the user's Things 3 (in sidebar order) with their tags. Use an area's name or id as the area filter of things_find_tasks or things_find_projects.

  Property	Type	Description
  limit	integer	maximum number of entries to return (default 100, max 500)
  offset	integer	number of entries to skip, for paging (default 0)

• Find headings of a projectthings_find_headings

  List the headings (sections) of one project in order, e.g. to pick a heading_uuid when creating or moving a to-do. project_uuid is the project's id, an id prefix or its name.

  Property	Type	Description
  project_uuid*	string	the project: its id, an unambiguous id prefix, or its exact name
  limit	integer	maximum number of entries to return (default 100, max 500)
  offset	integer	number of entries to skip, for paging (default 0)

• Find projectsthings_find_projects

  List projects from the user's Things 3. Takes the same filters as things_find_tasks except project: schedule, tag/tags, area (names or ids), date bounds, contains_text, status (pending by default) and in_trash. Results are in Things order and paged with limit/offset. Use things_show_project to see a project's headings and to-dos.

  Property	Type	Description
  area	string	only items in this area (directly or through their project): its name or id
  contains_text	string	only items whose title or notes contain this text (case-insensitive)
  created_after	string	only items created after this day (YYYY-MM-DD in the user's time zone, exclusive) or RFC 3339 time
  created_before	string	only items created before this day (YYYY-MM-DD in the user's time zone, exclusive) or RFC 3339 time
  deadline_after	string	only items whose deadline is after this date (YYYY-MM-DD, exclusive)
  deadline_before	string	only items whose deadline is before this date (YYYY-MM-DD, exclusive)
  in_trash	boolean	also include items in the Trash (default false)
  limit	integer	maximum number of entries to return (default 100, max 500)
  offset	integer	number of entries to skip, for paging (default 0)
  schedule	string	only items in this Things list: inbox, today (includes tonight), tonight, anytime (includes today's items, like the app), upcoming or someday
  scheduled_after	string	only items whose start date is after this date (YYYY-MM-DD, exclusive)
  scheduled_before	string	only items whose start date is before this date (YYYY-MM-DD, exclusive)
  status	string	pending (default), completed, canceled or any
  tag	string	only items with this tag: its name (case-insensitive) or id
  tags	—	only items with all of these tags: names or ids

• Find tagsthings_find_tags

  List all tags in the user's Things 3 with their shorthand and parent tag ids. Use a tag's name or id as the tag filter of other tools; things_tag_usage adds how often each tag is used.

  Property	Type	Description
  limit	integer	maximum number of entries to return (default 100, max 500)
  offset	integer	number of entries to skip, for paging (default 0)

• Find to-dosthings_find_tasks

  List to-dos from the user's Things 3, filtered like the Things app's lists. schedule picks a list; today, tonight and upcoming also include projects scheduled there (type=project). Narrow with tag/tags, area and project (names or ids), start, deadline and creation date bounds (exclusive) and contains_text. Only open to-dos in open projects unless status or in_trash say otherwise. Results come in Things order, paged with limit/offset; total counts all matches. For full-text search (checklists too) use things_search; for one to-do's details, things_show_task.

  Property	Type	Description
  area	string	only items in this area (directly or through their project): its name or id
  contains_text	string	only items whose title or notes contain this text (case-insensitive)
  created_after	string	only items created after this day (YYYY-MM-DD in the user's time zone, exclusive) or RFC 3339 time
  created_before	string	only items created before this day (YYYY-MM-DD in the user's time zone, exclusive) or RFC 3339 time
  deadline_after	string	only items whose deadline is after this date (YYYY-MM-DD, exclusive)
  deadline_before	string	only items whose deadline is before this date (YYYY-MM-DD, exclusive)
  in_trash	boolean	also include items in the Trash (default false)
  limit	integer	maximum number of entries to return (default 100, max 500)
  offset	integer	number of entries to skip, for paging (default 0)
  project	string	only to-dos in this project (directly or under one of its headings): its name or id
  schedule	string	only items in this Things list: inbox, today (includes tonight), tonight, anytime (includes today's items, like the app), upcoming or someday
  scheduled_after	string	only items whose start date is after this date (YYYY-MM-DD, exclusive)
  scheduled_before	string	only items whose start date is before this date (YYYY-MM-DD, exclusive)
  status	string	pending (default), completed, canceled or any
  tag	string	only items with this tag: its name (case-insensitive) or id
  tags	—	only items with all of these tags: names or ids

• Logbookthings_logbook

  List what the user completed or canceled in Things 3 within a date window, most recent first (completionDate says when). By default the last 7 days including today; set from/to (YYYY-MM-DD, inclusive, in the user's time zone) for another window and status to only see completed or canceled items. Items in the Trash are not listed. Paged with limit/offset.

  Property	Type	Description
  from	string	first day to include, YYYY-MM-DD in the user's time zone (default: 6 days before to)
  limit	integer	maximum number of entries to return (default 100, max 500)
  offset	integer	number of entries to skip, for paging (default 0)
  status	string	completed, canceled or any (default any)
  to	string	last day to include, YYYY-MM-DD in the user's time zone (default: today)

• Overview of Thingsthings_overview

  A one-call summary of the user's Things 3: all tags, all areas with their open projects (plus a (No Area) bucket), the Today list, and what starts or is due in the next lookahead_days days (default 7). Items are short summaries (id, title, list, dates, project, tag names); use things_show_task for full details. Use it first to get oriented; then drill down with things_find_tasks, things_show_project or things_show_task.

  Property	Type	Description
  lookahead_days	integer	how many days ahead upcomingTasks covers (default 7)

• Look up a changethings_receipt

  Look up a change made through this server by the receipt_id its write tool returned: which tool made it, whether Things Cloud applied it (applied, uncertain, unverifiable, conflict, failed, undone, ...), the items it touched, and whether things_undo can still reverse it (and if not, why). unverifiable means the user's Things history was reset before the change could be confirmed: ask the user to check the item in Things and do not repeat the change. Receipts are kept for 30 days.

  Property	Type	Description
  receipt_id*	string	the receipt_id a write tool returned

• Search to-dos and projectsthings_search

  Full-text search over the user's Things 3: titles, and by default notes and checklist items. Each result says where the text matched. Narrow it with type, status (pending by default), tag, area, project and include_trashed. Use this when the user remembers words rather than a list; use things_find_tasks for list-style filters.

  Property	Type	Description
  query*	string	text to look for (case-insensitive substring)
  area	string	only items in this area (name or id)
  in_checklist	—	also search checklist items (default true)
  in_notes	—	also search notes (default true)
  include_trashed	boolean	also search the Trash (default false)
  limit	integer	maximum number of entries to return (default 100, max 500)
  offset	integer	number of entries to skip, for paging (default 0)
  project	string	only items in this project (name or id)
  status	string	pending (default), completed, canceled or any
  tag	string	only items with this tag (name or id)
  type	string	task, project or any (default any)

• Show a projectthings_show_project

  Show one project with its details, its headings in order, and its to-dos in order (tasks): first those not under a heading, then each heading's; each to-do names its heading (null when none). status picks which to-dos are listed (pending by default; any for all). uuid is the project's id or an unambiguous prefix; it also finds completed and trashed projects.

  Property	Type	Description
  uuid*	string	the project's id or an unambiguous prefix of it (at least 4 characters)
  status	string	which to-dos to include: pending (default), completed, canceled or any

• Show a to-dothings_show_task

  Show one to-do with all its details: notes, dates, project, heading, area, tags and its checklist in order. uuid is the to-do's id or an unambiguous prefix of it; it also finds completed and trashed to-dos. For projects use things_show_project.

  Property	Type	Description
  uuid*	string	the to-do's id or an unambiguous prefix of it (at least 4 characters)

• Sync with Things Cloudthings_sync

  Fetch the latest changes from Things Cloud now, e.g. right after the user changed something in the Things app and other tools still show the old state. Reads already sync automatically when their data is older than 15 seconds, so this is rarely needed. It runs at most once every 30 seconds; the result says whether this call checked and which history index the data now reflects.

• Tag usagethings_tag_usage

  Count how many open to-dos and projects carry each tag, most used first, including unused tags with count 0. Useful for tidying tags or picking a tag filter. Paged with limit/offset.

  Property	Type	Description
  limit	integer	maximum number of entries to return (default 100, max 500)
  offset	integer	number of entries to skip, for paging (default 0)

• Trashthings_trash

  List the items in the user's Things 3 Trash (to-dos, projects and headings). To restore one, call things_edit_item with its uuid and status=restored; there is no separate restore tool. Paged with limit/offset.

  Property	Type	Description
  limit	integer	maximum number of entries to return (default 100, max 500)
  offset	integer	number of entries to skip, for paging (default 0)

Write tools

• Add a checklist itemthings_add_checklist_item

  Add an item to a to-do's checklist, after the last item or at index (0 = first). Only to-dos have checklists; things_show_task shows the checklist in order. Returns a receipt_id; things_undo with it reverses the change.

  Property	Type	Description
  task_uuid*	string	the to-do: id or unambiguous id prefix (at least 4 characters)
  title*	string	title of the checklist item
  index	—	position in the checklist, 0 = first; default: after the last item

• Change several items at oncethings_bulk_update

  Apply up to 50 changes to to-dos, projects or headings as ONE change: each entry of updates takes the fields of things_edit_item (uuid plus what to change). All or none are applied, and one things_undo reverses them all. Use it to complete, reschedule, retag or move several items; each item may appear once. Prefer trashing (things_edit_item with status trashed, which can be restored) over deleting. Returns a receipt_id; things_undo with it reverses the change.

  Property	Type	Description
  updates*	—	the changes, one entry per item (at most 50); every entry takes the fields of things_edit_item

• Create an areathings_create_area

  Create an area (a lasting area of responsibility such as Work or Family), optionally with tags. Returns a receipt_id; things_undo with it reverses the change.

  Property	Type	Description
  name*	string	name of the area
  tags	—	tags for the area, by name or id

• Create a headingthings_create_heading

  Add a heading to an open project, to group its to-dos. Put to-dos under it with things_create_task or things_edit_item (heading_uuid). Returns a receipt_id; things_undo with it reverses the change.

  Property	Type	Description
  project_uuid*	string	the open project to add it to: id, unambiguous id prefix, or exact name
  title*	string	title of the heading

• Create a projectthings_create_project

  Create a project, optionally in an area, with notes, a deadline and tags (by name or id). schedule takes today, tonight, anytime (default), someday or a date YYYY-MM-DD; projects cannot go to the Inbox. For Someday or a later date it is created, then scheduled in a second change (follow_up_receipt_id). Add headings with things_create_heading and to-dos with things_create_task. Repeating projects and reminders are not supported yet. Returns a receipt_id; things_undo with it reverses the change.

  Property	Type	Description
  title*	string	title of the project
  area_uuid	string	put the project in this area: id, unambiguous id prefix, or exact name
  deadline	string	deadline YYYY-MM-DD
  note	string	notes, plain text
  recurrence	string	repeat rule; repeating projects are read-only for now, so this is refused
  reminder_date	string	reminder date YYYY-MM-DD; reminders are read-only for now, so this is refused
  reminder_time	string	reminder time HH:MM; reminders are read-only for now, so this is refused
  schedule	string	when: today, tonight (This Evening), anytime (default), someday, or a date YYYY-MM-DD; projects cannot go to the Inbox
  tags	—	tags by name or id; they must exist (things_find_tags lists them, things_create_tag adds one)

• Create a tagthings_create_tag

  Create a tag, optionally with a keyboard shorthand and nested under a parent tag (by name or id). Tag names are unique. Put tags on items with things_create_task or things_edit_item (tags). Returns a receipt_id; things_undo with it reverses the change.

  Property	Type	Description
  name*	string	name of the tag
  parent_uuid	string	nest the tag under this tag: name or id
  shorthand	string	keyboard shorthand, e.g. a letter

• Create a to-dothings_create_task

  Create a to-do in the user's Things. Without schedule it goes to the Inbox, or to Anytime when a project, heading or area is given; schedule takes inbox, today, tonight, anytime, someday or a date (YYYY-MM-DD). Tags (existing ones, by name or id) and checklist items are JSON arrays. All of it is created in one change; the new id is in uuid. Repeating to-dos and reminders are not supported yet. Returns a receipt_id; things_undo with it reverses the change.

  Property	Type	Description
  title*	string	title of the to-do
  area_uuid	string	put the to-do directly in this area (id, id prefix or exact name); not together with project_uuid or heading_uuid
  checklist	—	checklist item titles, in order
  deadline	string	deadline YYYY-MM-DD
  heading_uuid	string	put the to-do under this heading (id or unambiguous id prefix); its project is implied
  note	string	notes, plain text
  project_uuid	string	put the to-do in this project: id, unambiguous id prefix, or exact name
  recurrence	string	repeat rule; repeating to-dos are read-only for now, so this is refused
  reminder_date	string	reminder date YYYY-MM-DD; reminders are read-only for now, so this is refused
  reminder_time	string	reminder time HH:MM; reminders are read-only for now, so this is refused
  schedule	string	when: inbox, today, tonight (This Evening), anytime, someday, or a date YYYY-MM-DD; default inbox, or anytime when a project, heading or area is given
  tags	—	tags by name or id; they must exist (things_find_tags lists them, things_create_tag adds one)

• Delete an areathings_delete_area

  Permanently delete an area. Areas have no Trash, so this cannot be undone and needs confirm: true; ask the user first. It is refused while any to-do or project still belongs to the area, including trashed and completed ones: move them out first (things_edit_item with area_uuid none). Returns a receipt_id; things_undo with it reverses the change.

  Property	Type	Description
  uuid*	string	the area: id, unambiguous id prefix, or exact name
  confirm	boolean	must be true: the deletion is permanent; ask the user first

• Delete a checklist itemthings_delete_checklist_item

  Permanently delete one checklist item. This cannot be undone, so it needs confirm: true; ask the user first. To keep the item but mark it done, use things_edit_checklist_item with completed true. Returns a receipt_id; things_undo with it reverses the change.

  Property	Type	Description
  uuid*	string	the checklist item: id or unambiguous id prefix
  confirm	boolean	must be true: the deletion is permanent; ask the user first

• Delete a tagthings_delete_tag

  Permanently delete a tag. Tags have no Trash, so this cannot be undone and needs confirm: true; ask the user first. It is refused while any item (including trashed and completed ones) or another tag's nesting still uses the tag: remove it from them first (things_edit_item with tags, things_edit_tag with parent_uuid); things_tag_usage shows where it is used. Returns a receipt_id; things_undo with it reverses the change.

  Property	Type	Description
  uuid*	string	the tag: id, unambiguous id prefix, or exact name
  confirm	boolean	must be true: the deletion is permanent; ask the user first

• Change an areathings_edit_area

  Rename an area and/or replace its tags (an empty list removes them). Returns a receipt_id; things_undo with it reverses the change.

  Property	Type	Description
  uuid*	string	the area: id, unambiguous id prefix, or exact name
  name	string	new name
  tags	—	replace the area's tags (names or ids); an empty list removes them

• Change a checklist itemthings_edit_checklist_item

  Change one checklist item: its title, whether it is checked off (completed true or false), or its position (index, 0 = first). Only the fields given change. Returns a receipt_id; things_undo with it reverses the change.

  Property	Type	Description
  uuid*	string	the checklist item: id or unambiguous id prefix (things_show_task lists a to-do's checklist)
  completed	—	true checks the item off, false unchecks it
  index	—	move it to this position in the checklist, 0 = first
  title	string	new title

• Change a to-do, project or headingthings_edit_item

  Change one to-do, project or heading; only the fields given change: title, notes ("" removes them), schedule (a list or a date), deadline (a date or none), container (area_uuid, project_uuid or heading_uuid; none takes it out of all; dates are kept), tags (replaces all; [] removes them) and status. Trashing needs no confirmation because restored brings the item back. Prefer trashing (things_edit_item with status trashed, which can be restored) over deleting. For several items use things_bulk_update. Repeating items and reminders are not supported yet. Returns a receipt_id; things_undo with it reverses the change.

  Property	Type	Description
  uuid*	string	the to-do, project or heading to change: id or unambiguous id prefix (at least 4 characters)
  area_uuid	string	move into this area (id, id prefix or exact name), or none to take the item out of its area, project and heading
  deadline	string	new deadline YYYY-MM-DD, or none to remove it
  heading_uuid	string	move under this heading (id or id prefix), or none to take the item out of every container
  note	—	new notes, replacing the old ones; an empty string removes them
  project_uuid	string	move into this project (id, id prefix or exact name), or none to take the item out of every container
  recurrence	string	repeat rule; repeating items are read-only for now, so this is refused
  reminder_date	string	reminder date YYYY-MM-DD; reminders are read-only for now, so this is refused
  reminder_time	string	reminder time HH:MM; reminders are read-only for now, so this is refused
  schedule	string	move to inbox, today, tonight (This Evening), anytime or someday, or schedule for a date YYYY-MM-DD (Upcoming)
  status	string	pending (reopen), completed, canceled, trashed (to the Trash) or restored (out of the Trash)
  tags	—	replace all tags with these (names or ids); an empty list removes every tag
  title	string	new title

• Change a tagthings_edit_tag

  Rename a tag, change or remove its keyboard shorthand ("" removes it), or nest it under another tag (parent_uuid; "" or none makes it top-level). Only the fields given change. Returns a receipt_id; things_undo with it reverses the change.

  Property	Type	Description
  uuid*	string	the tag: id, unambiguous id prefix, or exact name
  name	string	new name
  parent_uuid	—	nest it under this tag (name or id); an empty string or none makes it a top-level tag
  shorthand	—	new keyboard shorthand; an empty string removes it

• Settingsthings_settings

  Show or change this server's settings for the user: the time zone used for Today, deadlines and dates, and read-only mode (no changes are written; reading still works). Without arguments it shows the current settings. Changes apply at once and make no request to Things Cloud. The assistant can switch read-only mode on but not off: only the user can, on their account page.

  Property	Type	Description
  read_only	—	true stops every change through this server (reading still works). Only the user can switch it off again, on their account page
  timezone	string	IANA time zone used for Today, deadlines and dates, e.g. Europe/Berlin or America/New_York

• Undo a changethings_undo

  Reverse a change made through this server, given the receipt_id its tool returned. Created to-dos, projects and headings go to the Trash; created areas, tags and checklist items are deleted; edits get their old values back, in one change (a bulk update as a whole). Refused when the same fields changed since (e.g. in the Things app), for deletions and for an undo; things_receipt says whether a change can still be undone. Returns its own receipt_id.

  Property	Type	Description
  receipt_id*	string	the receipt_id a write tool returned