API Reference

The Throw It On The List site exposes a full REST API under the tiotl/v1 namespace. All routes are mounted at /wp-json/tiotl/v1/ on this site.

Authentication

Most endpoints require an authenticated user. Authentication is handled through the following mechanisms:

• Cookie + Nonce — Used by the in-app frontend. Pass the X-WP-Nonce header (available in JS as tiotlData.nonce).
• Application Passwords — Used by external integrations. Generate one via POST /applications and authenticate with HTTP Basic Auth.

Permission tiers used throughout the API:

• Public — No authentication required.
• Logged in — Any authenticated user.
• List viewer — Read access to a specific list (owner, editor, viewer, or valid link/password share).
• List editor — Write access to a list (owner or editor role).
• List owner — Owner-only operations (settings, sharing, deletion).

Lists

Manage titl_list CPT entries — the top-level container for tasks.

Method	Route	Description	Auth
GET	/lists	List all lists accessible to the current user.	Logged in
POST	/lists	Create a new list. Body: title (required), description, color, icon, visibility, default_view, password_viewer, password_editor.	Logged in
GET	/lists/{id}	Retrieve a single list.	List viewer
PUT/PATCH	/lists/{id}	Update list metadata.	List owner
DELETE	/lists/{id}	Permanently delete a list (cascades to states, items, activity).	List owner
POST	/lists/{id}/share/invite	Invite a user by username/email with a role.	List owner
PATCH	/lists/{id}/share/members/{user_id}	Update a member’s role.	List owner
DELETE	/lists/{id}/share/members/{user_id}	Remove a member from a list.	List owner
POST	/lists/{id}/share/token	Generate a public share token. Body: access (viewer or editor).	List owner
POST	/lists/{id}/unlock	Unlock a password-protected list. Body: password.	Public

States

Manage titl_state CPT entries — the kanban columns / workflow stages within a list.

Method	Route	Description	Auth
GET	/lists/{list_id}/states	Retrieve all states for a list.	List viewer
POST	/lists/{list_id}/states	Create a state. Body: name (required), color, icon, order, is_default, is_complete.	List owner
PUT/PATCH	/lists/{list_id}/states/{state_id}	Update state name, color, icon, default, or complete flags.	List owner
DELETE	/lists/{list_id}/states/{state_id}	Delete a state. Body: migrate_to_state_id if the state contains items.	List owner
PUT	/lists/{list_id}/states/reorder	Persist column order. Body: order (array of state IDs).	List owner

Items

Manage titl_item CPT entries — the individual tasks. Items belong to a list and live in a state.

Method	Route	Description	Auth
GET	/lists/{list_id}/items	List items in a list. Query: state_id, priority, tag, assignee, due, search, page, per_page.	List viewer
POST	/lists/{list_id}/items	Create an item. Body: title (required), description, state_id, priority_id, assignees, due_date.	List editor
GET	/lists/{list_id}/items/{item_id}	Retrieve a single item.	List viewer
PUT/PATCH	/lists/{list_id}/items/{item_id}	Update an item’s fields.	List editor
DELETE	/lists/{list_id}/items/{item_id}	Delete an item permanently (cascades to attachments and comments).	List owner
POST	/lists/{list_id}/items/{item_id}/move	Move an item to a different state. Body: state_id.	List editor
POST	/lists/{list_id}/items/reorder	Reorder items within a state. Body: state_id, order.	List editor
POST	/lists/{list_id}/items/{item_id}/attachments	Upload an image attachment (multipart).	List editor
DELETE	/lists/{list_id}/items/{item_id}/attachments/{attachment_id}	Remove an image attachment.	List editor
POST	/lists/{list_id}/items/{item_id}/files	Upload a file attachment (multipart).	List editor
DELETE	/lists/{list_id}/items/{item_id}/files/{attachment_id}	Remove a file attachment.	List editor

My Items

Cross-list view of items assigned to the current user.

Method	Route	Description	Auth
GET	/items/assigned	Items assigned to current user across every list. Query: state_id, priority, tag, due, search, page, per_page.	Logged in

Priorities

List-scoped titl_priority taxonomy terms.

Method	Route	Description	Auth
POST	/lists/{list_id}/priorities	Create a priority. Body: name (required), color.	List owner
PATCH	/lists/{list_id}/priorities/{term_id}	Update name and/or color.	List owner
PUT	/lists/{list_id}/priorities/reorder	Persist priority order. Body: order (array of term IDs).	List owner

Activity

Read the activity feed stored in the {prefix}titl_activity table.

Method	Route	Description	Auth
GET	/lists/{id}/activity	Paginated activity feed. Query: page, per_page (max 50).	List viewer
GET	/lists/{id}/activity/latest	Latest activity ID — used for cheap freshness polling.	List viewer

Notifications

In-app notification feed and per-user notification preferences.

Method	Route	Description	Auth
GET	/notifications	Retrieve current user’s notifications.	Logged in
GET	/notifications/latest	Latest notification ID + unread count for polling.	Logged in
POST	/notifications/{id}/read	Mark a single notification as read.	Logged in
POST	/notifications/read-all	Mark every notification as read.	Logged in
GET	/notifications/preferences	Get the current user’s notification preferences.	Logged in
POST	/notifications/preferences	Update preferences. Body: assigned, comment, invited, due_soon (booleans).	Logged in

Invitations

Accept or decline pending list invitations.

Method	Route	Description	Auth
GET	/invitations/pending	Retrieve pending invitations for the current user.	Logged in
POST	/invitations/{token}/accept	Accept a list invitation by token.	Logged in
POST	/invitations/{token}/decline	Decline a list invitation by token.	Logged in

Preferences

Per-user app preferences (default list, page URL map).

Method	Route	Description	Auth
GET	/preferences	Get current user’s preferences.	Logged in
PUT/PATCH	/preferences	Update preferences. Body: default_list_id.	Logged in

Profile

Read and update the current user’s WordPress profile.

Method	Route	Description	Auth
GET	/profile	Get the current user’s profile (name, email, avatar).	Logged in
POST	/profile	Update profile. Body: first_name, last_name, display_name, email, current_password, new_password. Email and password changes require current_password.	Logged in

Applications

Manage WordPress Application Passwords for the current user — used by external integrations to authenticate against the TIOTL API.

Method	Route	Description	Auth
GET	/applications	List the current user’s application passwords.	Logged in
POST	/applications	Create a new application password. Body: name (required), app_id (optional UUID).	Logged in
DELETE	/applications/{uuid}	Revoke an application password.	Logged in

Reference

• REST namespace: tiotl/v1
• Visibility values: private, invite, link, password
• List role values: owner, editor, viewer
• Default view values: checklist, kanban
• CPT slugs: titl_list, titl_state, titl_item
• Taxonomy slugs: titl_tag, titl_priority