From 2b29c5c56db6d315d546fa7f58edae1597d8ceea Mon Sep 17 00:00:00 2001 From: Rob Zolkos Date: Thu, 12 Mar 2026 15:29:28 -0400 Subject: [PATCH 1/2] Add notification settings and snooze API documentation (#9931) --- README.md | 1 + sections/notification_settings.md | 141 ++++++++++++++++++++++++++++++ 2 files changed, 142 insertions(+) create mode 100644 sections/notification_settings.md diff --git a/README.md b/README.md index 5bc1cbb..446e1b6 100644 --- a/README.md +++ b/README.md @@ -305,6 +305,7 @@ API endpoints - [Message Boards](https://github.com/basecamp/bc3-api/blob/master/sections/message_boards.md#message-boards) - [Message Types](https://github.com/basecamp/bc3-api/blob/master/sections/message_types.md#message-types) - [Messages](https://github.com/basecamp/bc3-api/blob/master/sections/messages.md#messages) +- [Notification settings](https://github.com/basecamp/bc3-api/blob/master/sections/notification_settings.md#notification-settings) - [People](https://github.com/basecamp/bc3-api/blob/master/sections/people.md#people) - [Projects](https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#projects) - [Question answers](https://github.com/basecamp/bc3-api/blob/master/sections/question_answers.md#question-answers) diff --git a/sections/notification_settings.md b/sections/notification_settings.md new file mode 100644 index 0000000..eb0c621 --- /dev/null +++ b/sections/notification_settings.md @@ -0,0 +1,141 @@ +Notification settings +===================== + +Endpoints for reading and updating the current user's notification preferences, including delivery platform, granularity, schedule, reminders, and snoozing. + +Endpoints: + +- [Get notification settings](#get-notification-settings) +- [Update notification settings](#update-notification-settings) +- [Snooze notifications](#snooze-notifications) + + +Get notification settings +------------------------- + +* `GET /my/notifications/settings.json` will return the current user's notification settings. + +###### Example JSON Response + +```json +{ + "platform": "web_and_email", + "granularity": "everything", + "show_badge_counts": true, + "schedule_enabled": false, + "schedule": null, + "bundle_enabled": true, + "schedule_entries_reminders": true, + "due_assignments_reminders": true, + "state": "on" +} +``` + + +When `schedule_enabled` is `true`, the `schedule` object is included: + +```json +{ + "schedule_enabled": true, + "schedule": { + "start_hour": 9, + "end_hour": 17, + "work_days": [1, 2, 3, 4, 5] + } +} +``` + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/my/notifications/settings.json +``` + + +Update notification settings +---------------------------- + +* `PUT /my/notifications/settings.json` will update the current user's notification settings. Only the provided parameters are changed; omitted parameters remain unchanged. Returns `204 No Content` on success. + +_Optional parameters_: + +* `platform` - delivery platform. Valid options: `web`, `email`, `web_and_email`. +* `granularity` - notification granularity. Valid options: `everything`, `pings_and_mentions`. +* `show_badge_counts` - whether to show badge counts. `true` or `false`. +* `schedule_enabled` - whether the notification schedule is active. `true` or `false`. When `true`, also provide `schedule`. +* `schedule` - an object with `start_hour` (integer 0–23), `end_hour` (integer 0–23), and `work_days` (array of integers, 0=Sunday through 6=Saturday). +* `bundle_enabled` - whether notification bundling is enabled. `true` or `false`. Requires `schedule_enabled` to be `true`. +* `reminders` - an array of reminder types to enable. Valid values: `schedule_entries`, `due_assignments`. Pass an empty array to disable all reminders. + +Providing an invalid `platform` or `granularity` returns `422 Unprocessable Entity` with an error listing the valid options: + +```json +{ + "errors": [ + "Invalid platform 'carrier_pigeon'. Valid options: web, email, web_and_email" + ] +} +``` + +###### Example JSON Request + +```json +{ + "platform": "email", + "granularity": "pings_and_mentions", + "schedule_enabled": true, + "schedule": { + "start_hour": 9, + "end_hour": 17, + "work_days": [1, 2, 3, 4, 5] + }, + "bundle_enabled": true, + "reminders": ["schedule_entries", "due_assignments"] +} +``` + + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ + -d '{"platform":"email","granularity":"pings_and_mentions"}' -X PUT \ + https://3.basecampapi.com/$ACCOUNT_ID/my/notifications/settings.json +``` + + +Snooze notifications +-------------------- + +* `PUT /my/notifications/snooze.json` will snooze the current user's notifications for the given duration. Returns `200 OK` with the snooze state. + +**Required parameters**: + +* `duration` - the number of seconds to snooze notifications. + +###### Example JSON Response + +```json +{ + "state": "snoozed", + "off_until": "2024-12-05T15:00:00Z" +} +``` + + +###### Example JSON Request + +```json +{ + "duration": 10800 +} +``` + + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ + -d '{"duration":10800}' -X PUT \ + https://3.basecampapi.com/$ACCOUNT_ID/my/notifications/snooze.json +``` From 02396858c4e5c4cb58b39b215e5dccc043b7982b Mon Sep 17 00:00:00 2001 From: Rob Zolkos Date: Thu, 12 Mar 2026 15:33:47 -0400 Subject: [PATCH 2/2] Remove incorrect bundle_enabled/schedule_enabled constraint --- sections/notification_settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sections/notification_settings.md b/sections/notification_settings.md index eb0c621..8a16439 100644 --- a/sections/notification_settings.md +++ b/sections/notification_settings.md @@ -64,7 +64,7 @@ _Optional parameters_: * `show_badge_counts` - whether to show badge counts. `true` or `false`. * `schedule_enabled` - whether the notification schedule is active. `true` or `false`. When `true`, also provide `schedule`. * `schedule` - an object with `start_hour` (integer 0–23), `end_hour` (integer 0–23), and `work_days` (array of integers, 0=Sunday through 6=Saturday). -* `bundle_enabled` - whether notification bundling is enabled. `true` or `false`. Requires `schedule_enabled` to be `true`. +* `bundle_enabled` - whether notification bundling is enabled. `true` or `false`. * `reminders` - an array of reminder types to enable. Valid values: `schedule_entries`, `due_assignments`. Pass an empty array to disable all reminders. Providing an invalid `platform` or `granularity` returns `422 Unprocessable Entity` with an error listing the valid options: