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

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

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

```bash
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](https://thread.page/help/connections/errors.md#errors-every-call-can-get), 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 |

```bash
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](https://thread.page/help/connections/errors.md#errors-every-call-can-get), 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](#getThreadReminder).

```bash
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](https://thread.page/help/connections/errors.md#errors-every-call-can-get), 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.

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

```bash
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](https://thread.page/help/connections/errors.md#errors-every-call-can-get), 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`

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 |
|---|---|---|
| `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](#setThreadReminder).

```bash
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}'
```

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](https://thread.page/help/connections/errors.md#errors-every-call-can-get), 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](#setThreadReminder).

```bash
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](https://thread.page/help/connections/errors.md#errors-every-call-can-get), 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](#setThreadReminder).

```bash
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](https://thread.page/help/connections/errors.md#errors-every-call-can-get), 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 |

## Next

- [Events and subscriptions](https://thread.page/help/connections/events.md): `reminder.set`, `reminder.changed` and `reminder.removed`.
- [Threads and folders](https://thread.page/help/connections/api/threads.md)