Update the current user's notification preferences
Updates the calling user's notification preferences. Pass a
partial of the same shape returned by GET /v1/me/notifications: absent keys leave the stored value
alone, explicit booleans replace, and null is rejected.
An empty body is a valid no-op that returns the current
state.
Sending a key outside the documented schema (an unknown
channel like in_app before it ships, or an unknown toggle
inside email) produces 422 UNKNOWN_NOTIFICATION_KEY so
a typo fails fast instead of silently no-opping. Attempting
to set email.security_alerts produces
422 IMMUTABLE_NOTIFICATION_KEY, critical security alerts
are not user-toggleable.
Returns the full resolved (post-defaults) notification preferences so the FE can use the response as a refresh.
Requires a user session. API-key principals receive
403 USER_REQUIRED.
Authorization
clerkJWT First-party clients (the dashboard) authenticate with the session token issued at sign-in. Requests are scoped to the active organization and the signed-in user's role.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/v1/me/notifications" \ -H "Content-Type: application/json" \ -d '{ "email": { "weekly_usage_digest": true } }'{
"success": true,
"error": {
"code": "string",
"message": "string",
"request_id": "string",
"details": {
"property1": "string",
"property2": "string"
}
},
"meta": {
"total": 0,
"limit": 0,
"offset": 0,
"next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNC0yNlQxMjowMDowMFoiLCJpZCI6IjAxOTAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMSJ9",
"last_event_at": "2019-08-24T14:15:22Z"
},
"data": {
"email": {
"product_updates": true,
"delivery_alerts": true,
"billing_receipts": true,
"weekly_usage_digest": false
}
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "USER_REQUIRED",
"message": "endpoint requires a user session",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "UNKNOWN_NOTIFICATION_KEY",
"message": "unknown notification key",
"details": {
"email.product_news": "unknown toggle"
},
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}