Reminders

A reminder brings a thread or a note back to the person at a time they choose, once or on a repeat. It has no text, and only the person sees it. A thread has one general reminder, and each of its notes can have one.

View as Markdown

On this page

The reminder object
Read reminders
Set a weekly reminder
Replace a reminder
Remove a reminder
If it fails
Next

The reminder object

thread_id, and note_id for a note’s reminder (null for the thread’s own).
rule: a wall date and time in the person’s own time zone, {date, time, repeat}, with date as YYYY-MM-DD and time as HH:MM. repeat is null for once, at a time in the future; otherwise every is day, weekday, week, month or year. A weekly rule takes interval 1 or 2. A monthly rule takes on: day (the default), last_day (the date must be its month’s last day) or weekday.
next_at and snooze_at: when it next comes due and, if the person snoozed it, until when.
due: whether it is due now.
set_by: the connection that set it, or null when the person did.

The reminder object
Level	Reminders
Read only	Read them.
Read and add	Read them, set new ones, and replace or remove the ones it set (`set_by` is this connection).
Edit and organize	Read, set, replace and remove any.

Changing or removing a reminder the connection did not set, on Read and add, answers 403 edit_not_allowed. A reminder is the person’s alone, so it is not a write into a shared thread.

Read reminders

List a thread's reminders

GET /api/integrations/v1/threads/{thread_id}/reminders

The thread's general reminder and those on its notes, each with its rule, next time, whether it is due and set_by. Read only and up.

Requirements
Requirement	Value
Levels	Edit and organize · Read and add · Read only
Plan	Pro with Sync. On Free, add to the Inbox instead (`POST /inbox/notes`).
MCP	`list_reminders`

Parameters
Name	In	Type
`thread_id`	path	uuid, required

Answer 200.

Answer fields
Field	Type
`reminders`	array of object, required

curl

curl -m 30 "https://thread.page/api/integrations/v1/threads/$THREAD_ID/reminders" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN"

Errors: read_not_allowed 403, unavailable 404.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Read the person's reminder on this thread

GET /api/integrations/v1/threads/{thread_id}/reminder

The person's own reminder here, or null. It has no text and nobody else sees it. Read only and up.

Requirements
Requirement	Value
Levels	Edit and organize · Read and add · Read only
Plan	Pro with Sync. On Free, add to the Inbox instead (`POST /inbox/notes`).
MCP	`get_reminder`

Parameters
Name	In	Type
`thread_id`	path	uuid, required

Answer 200.

Answer fields
Field	Type
`reminder`	object or or null or null, required

curl

curl -m 30 "https://thread.page/api/integrations/v1/threads/$THREAD_ID/reminder" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN"

Errors: read_not_allowed 403, unavailable 404.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Read the person's reminder on this note

GET /api/integrations/v1/notes/{note_id}/reminder

The person's own reminder here, or null. It has no text and nobody else sees it. Read only and up.

Requirements
Requirement	Value
Levels	Edit and organize · Read and add · Read only
Plan	Pro with Sync. On Free, add to the Inbox instead (`POST /inbox/notes`).
MCP	`get_reminder`

Parameters
Name	In	Type
`note_id`	path	uuid, required

Answer 200. Its fields are those under Read the person's reminder on this thread.

curl

curl -m 30 "https://thread.page/api/integrations/v1/notes/$NOTE_ID/reminder" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN"

Errors: read_not_allowed 403, unavailable 404.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Set a weekly reminder

PUT /threads/{thread_id}/reminder sets the thread’s reminder; PUT /notes/{note_id}/reminder sets a note’s. The thread must accept notes from this connection.

Shell

OP=$(uuidgen)
curl -X PUT -m 30 --retry 3 --retry-all-errors https://thread.page/api/integrations/v1/threads/$THREAD_ID/reminder \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP" \
  -H "Content-Type: application/json" \
  -d '{"rule": {"date": "2026-11-02", "time": "09:00", "repeat": {"every": "week", "interval": 1}}}'

The ChangeReceipt carries the reminder as set in reminder.

Set the person's reminder on this thread

PUT /api/integrations/v1/threads/{thread_id}/reminder

The MCP tool set_reminder. Without replace an existing reminder is never overwritten: 409 reminder_exists with it. Read and add sets new reminders and replaces only its own (set_by); Edit and organize, any. The thread must accept notes from this connection.

Requirements
Requirement	Value
Levels	Edit and organize · Read and add
Plan	Pro with Sync. On Free, add to the Inbox instead (`POST /inbox/notes`).
Idempotency	`Operation-Id` header: one UUID per logical write, the same on every retry.
MCP	`set_reminder`
Shared threads	Only where the owner chose Allow here.

Parameters
Name	In	Type
`thread_id`	path	uuid, required

Body (application/json)
Field	Type	Description
`rule`	object, required	A wall date and time in the person's own zone.
`replace`	boolean	true replaces the reminder already here; only when the person asked.

Answer 200.

Answer fields
Field	Type	Description
`operation_id`	uuid, required
`status`	`accepted`, `conflict`, `not_completed`, required
`kind`	`note.update`, `note.properties`, `note.move`, `note.trash`, `note.restore`, `note.restore_version`, `thread.create`, `thread.update`, `thread.archive`, `thread.unarchive`, `thread.trash`, `thread.restore`, `thread.move`, `folder.create`, `folder.rename`, `folder.move`, `folder.trash`, `folder.restore`, `reminder.set`, `reminder.remove`, required
`target`	object, required
`revision`	integer or null	The target's revision after the change (informational).
`content_revision`	integer or null	A note's content revision after a content change.
`accepted_at`	date-time, required
`url`	uri or null
`thread_status`	string	thread.update: the status the Thread has after the change, which is the replacement when the one you sent was deleted.
`reminder`	object or or null or null	reminder.set: the reminder as set; reminder.remove: null.

curl

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X PUT "https://thread.page/api/integrations/v1/threads/$THREAD_ID/reminder" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP" \
  -H "Content-Type: application/json" \
  -d '{"rule":{"date":"2026-11-09","time":"09:00","repeat":{"every":"week"}}}'

Errors: write_not_allowed 403, 409, unavailable 404, invalid_json 400, invalid_rule 400, unsupported_media_type 415, operation_id_reused 409, shared_place_write 409, reminder_exists 409, thread_archived 409, entity_deleted 409, reminders_limit 422.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Set the person's reminder on this note

PUT /api/integrations/v1/notes/{note_id}/reminder

Requirements
Requirement	Value
Levels	Edit and organize · Read and add
Plan	Pro with Sync. On Free, add to the Inbox instead (`POST /inbox/notes`).
Idempotency	`Operation-Id` header: one UUID per logical write, the same on every retry.
MCP	`set_reminder`
Shared threads	Only where the owner chose Allow here.

Parameters
Name	In	Type
`note_id`	path	uuid, required

Body (application/json)
Field	Type	Description
`rule`	object, required	A wall date and time in the person's own zone.
`replace`	boolean	true replaces the reminder already here; only when the person asked.

Answer 200. Its fields are those under Set the person's reminder on this thread.

curl

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X PUT "https://thread.page/api/integrations/v1/notes/$NOTE_ID/reminder" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP" \
  -H "Content-Type: application/json" \
  -d '{"rule":{"date":"2026-11-03","time":"14:30","repeat":null},"replace":true}'

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Replace a reminder

Without replace, an existing reminder is never overwritten: the answer is 409 reminder_exists with the reminder that is there. Send "replace": true only when the person asked to change it.

JSON

{"rule": {"date": "2026-11-03", "time": "08:30", "repeat": null}, "replace": true}

Remove a reminder

DELETE removes it. The person can bring it back in ThreadPage for a day. Where there is no reminder, the answer is 404 not_found.

Remove the person's reminder on this thread

DELETE /api/integrations/v1/threads/{thread_id}/reminder

The MCP tool remove_reminder; the person can bring it back in ThreadPage for a day. Read and add removes only its own (set_by); Edit and organize, any. No reminder here answers 404.

Requirements
Requirement	Value
Levels	Edit and organize · Read and add
Plan	Pro with Sync. On Free, add to the Inbox instead (`POST /inbox/notes`).
Idempotency	`Operation-Id` header: one UUID per logical write, the same on every retry.
MCP	`remove_reminder`
Shared threads	Only where the owner chose Allow here.

Parameters
Name	In	Type
`thread_id`	path	uuid, required

Answer 200. Its fields are those under Set the person's reminder on this thread.

curl

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X DELETE "https://thread.page/api/integrations/v1/threads/$THREAD_ID/reminder" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP"

Errors: edit_not_allowed 403, unavailable 404, not_found 404, operation_id_reused 409, shared_place_write 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

Remove the person's reminder on this note

DELETE /api/integrations/v1/notes/{note_id}/reminder

The MCP tool remove_reminder; the person can bring it back in ThreadPage for a day. Read and add removes only its own (set_by); Edit and organize, any. No reminder here answers 404.

Requirements
Requirement	Value
Levels	Edit and organize · Read and add
Plan	Pro with Sync. On Free, add to the Inbox instead (`POST /inbox/notes`).
Idempotency	`Operation-Id` header: one UUID per logical write, the same on every retry.
MCP	`remove_reminder`
Shared threads	Only where the owner chose Allow here.

Parameters
Name	In	Type
`note_id`	path	uuid, required

Answer 200. Its fields are those under Set the person's reminder on this thread.

curl

OP=$(uuidgen)
curl -m 30 --retry 3 --retry-all-errors -X DELETE "https://thread.page/api/integrations/v1/notes/$NOTE_ID/reminder" \
  -H "Authorization: Bearer $THREADPAGE_TOKEN" \
  -H "Operation-Id: $OP"

Errors: edit_not_allowed 403, unavailable 404, not_found 404, operation_id_reused 409, shared_place_write 409.

Also the errors of every call, and pro_required or cloud_required without Pro and Sync.

If it fails

Errors
Code	HTTP	When	What to do	Retryable
`edit_not_allowed`	403	Changing a note this connection did not add, or a reminder it did not set, on Read and add; any change below Read and add.	Add a new note instead, or give the person details.manage_url.	No
`reminder_exists`	409	The person already has a reminder there and replace was not set.	Send replace true only when the person asked to change it.	No
`invalid_rule`	400	A reminder rule ThreadPage can't take, or a one-time reminder already past.	Fix the rule as the reminder routes describe it.	No
`reminders_limit`	422	The thread, or the person, has as many reminders as they may (details.scope).	Tell the person.	No
`invalid_request`	400, 422	A parameter, field or header is missing or has an unsupported value (a write without Operation-Id too), or the token was sent in the query string.	Fix what the message names. Sending it unchanged fails again.	No
`not_found`	404	No such request, subscription, delivery, endpoint, reminder or operation for this connection.	Check the ID; it may have expired or been deleted.	No
`thread_archived`	409	The thread is archived, so it takes no new notes.	Unarchive it first, or ask the owner.	No
`entity_deleted`	409	The item is in Trash.	Restore it first, or ask the owner.	No
`operation_id_reused`	409	The Operation-Id (MCP: operation_id) was already used with another body.	If you are repeating a lost write, read GET /operations/{id} first. Otherwise use a new ID.	No

Events and subscriptions: reminder.set, reminder.changed and reminder.removed.
Threads and folders

Reminders

The reminder object

Read reminders

List a thread's reminders

Read the person's reminder on this thread

Read the person's reminder on this note

Set a weekly reminder

Set the person's reminder on this thread

Set the person's reminder on this note

Replace a reminder

Remove a reminder

Remove the person's reminder on this thread

Remove the person's reminder on this note

If it fails

Next