Skip to content
GitmoapAPIBeta
Organizenotifications
PATCH/user/notifications/preferences

Change your notification preferences

update_my_notification_preferences
  • notification:manage
    A token needs the notification:manage scope: Change how and when notifications reach youGranted by write_api.Every operation this scope unlocks
  • Audited · mutation

    x-gitmoap-audit: {"kind":"audited","arg":"mutation"}

Set how a category reaches you on a channel — immediate, digest (email only) or off — and change your time zone, quiet hours, digest hour or digest frequency. Anything you leave out is unchanged, and the answer is all of your preferences as they now are. A category that tells you about something only a person can settle, such as an escalation, cannot be turned off.

Request body

application/json
  • digest_frequencyDigestFrequencyhourlydailyor nulloptionalHourly or daily digests.
  • digest_hourinteger · int32 or nulloptional0–23A new digest hour, 0 to 23.
  • preferencesarray of NotificationPreferenceChangeoptionalCategories to change, each on one channel. At most one entry per category and channel.
    • The NotificationPreferenceChange schema
    • categoryNotificationCategorygate_requestedgate_expiringescalationquestion_to_youmentiondigest_readybudget_thresholdritual_inviteThe category to change.
    • channelNotificationChannelin_appemailThe channel to change it on.
    • modeNotificationModeimmediatedigestoffHow it should reach you there. digest is for email only, and a category that cannot be turned off takes anything but off.
  • quiet_hoursQuietHours or nulloptionalNew quiet hours, or null for email that is never held back.
    • The QuietHours schema
    • from_hourinteger · int320–23The first quiet hour, 0 to 23, in your time zone.
    • until_hourinteger · int320–23The hour email may be sent again, 0 to 23, in your time zone. Differs from from_hour.
  • time_zoneTimeZoneName (string) or nulloptionalA new time zone.
Request body exampleSynthesized example
{}

Responses

200Your notification preferences, changedapplication/json
  • preferencesarray of NotificationPreferenceOne entry per category and channel, whether you have changed it or not.
    • The NotificationPreference schema
    • categoryNotificationCategorygate_requestedgate_expiringescalationquestion_to_youmentiondigest_readybudget_thresholdritual_inviteWhat the notification is about.
    • channelNotificationChannelin_appemailWhere it reaches you.
    • modeNotificationModeimmediatedigestoffHow it reaches you there — your choice, or the category's default.
    • requiredbooleanWhether the category cannot be turned off.
  • settingsNotificationSettingsWhen email may reach you.
    • The NotificationSettings schema
    • digest_frequencyDigestFrequencyhourlydailyWhether digests are sent hourly or daily.
    • digest_hourinteger · int320–23The local hour, 0 to 23, a daily digest is sent at.
    • time_zoneTimeZoneName (string)The time zone your quiet hours and digest hour are in.
    • quiet_hoursQuietHours or nulloptionalHours in which email waits, unless what it reports cannot be turned off. Absent when email is never held back.
      • The QuietHours schema
      • from_hourinteger · int320–23The first quiet hour, 0 to 23, in your time zone.
      • until_hourinteger · int320–23The hour email may be sent again, 0 to 23, in your time zone. Differs from from_hour.
200 exampleSynthesized example
{
"preferences": [
{
"category": "gate_requested",
"channel": "in_app",
"mode": "immediate",
"required": false
},
{
"category": "gate_requested",
"channel": "in_app",
"mode": "immediate",
"required": false
}
],
"settings": {
"digest_frequency": "hourly",
"digest_hour": 20,
"time_zone": "time-zone-7a98",
"quiet_hours": {
"from_hour": 2,
"until_hour": 17
}
}
}
400A value is not valid: an hour outside 0 to 23, a digest for the in-app channel, a category named twiceapplication/json
Error codes
  • BAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type
  • VALIDATION_ERRORA value is outside what the operation accepts; the message says which
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
400 exampleSynthesized example
{
"error": {
"code": "code-3296",
"message": "Label every synthesized example"
}
}
401Not authenticatedapplication/json
Error codes
  • UNAUTHORIZEDNo credential was sent, or the one sent is invalid, expired or revoked
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
401 exampleSynthesized example
{
"error": {
"code": "code-a6a2",
"message": "Label every synthesized example"
}
}
403The caller is not a personapplication/json
Error codes
  • FORBIDDENYou are signed in but may not do this here; reason names the permission or the rule that refused it
  • INSUFFICIENT_SCOPEThe access token lacks the scope this operation needs; required_scope names it
  • PERMISSION_REQUIREDYou need a permission you do not hold here; the message names it
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
403 exampleSynthesized example
{
"error": {
"code": "code-5806",
"message": "Draw the region map from operation density"
}
}
409The request conflicts with the resource's current state; `reason` says howapplication/json
Error codes
  • CONFLICTThe request conflicts with the resource's current state; reason says how
  • LEGAL_ACCEPTANCE_REQUIREDAccept the current Terms of Service before changing anything; reading stays open
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
409 exampleSynthesized example
{
"error": {
"code": "code-eefb",
"message": "Pin a page's payload to the build that rendered it"
}
}
422The category cannot be turned offapplication/json
Error codes
  • REQUIRED_NOTIFICATIONThe notification tells you about something only a person can settle, so it cannot be turned off; it can still reach you in a digest
  • UNPROCESSABLE_ENTITYThe request is well-formed but asks for something the resource's rules do not allow; reason says which
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
422 exampleSynthesized example
{
"error": {
"code": "code-496b",
"message": "Inline scalar newtypes but keep their brand"
}
}

CLI

gitmoap notifications update-my-notification-preferences

  • --digest-frequencyhourly | dailyoptional
  • --digest-hournumberoptionalA new digest hour, 0 to 23.
  • --preferencesjsonoptionalCategories to change, each on one channel. At most one entry per category and channel.
  • --quiet-hoursjsonoptional
  • --time-zonestringoptional