Notifications & Settings

Manage notifications, configure user and organization settings, and define alert rules for automated notification delivery.

Notifications

List Notifications

GET /v1/notifications

Lists notifications for the current user. The organization is taken from the authenticated session.

Query Parameters

Response

{
  "data": {
    "notifications": [
      {
        "id": "...",
        "notification_type": "info",
        "title": "New member joined",
        "body": "Jane Smith joined the Engineering team",
        "is_read": false,
        "action_url": "https://app.backbuild.ai/org/members",
        "created_at": "2026-04-12T15:30:00Z"
      }
    ]
  }
}

Mark Notification as Read

PUT /v1/notifications/:id

Request Body

{
  "is_read": true
}

The same endpoint also accepts is_archived to archive or unarchive a notification.

Delete Notification

DELETE /v1/notifications/:id

Settings

User and organization settings live under separate endpoints rather than a single scoped endpoint. The organization is taken from the authenticated session.

Get Personalization (User) Settings

GET /v1/settings/personalization

Response

{
  "data": {
    "themeMode": "system",
    "language": "en",
    "stayLoggedInHours": 720,
    "notifications": {
      "emailNotifications": true,
      "pushNotifications": true,
      "weeklyDigest": false,
      "mentionAlerts": true
    }
  }
}

Update Personalization (User) Settings

PUT /v1/settings/personalization

themeMode is one of light, dark, or system. stayLoggedInHours accepts one of the discrete choices 1, 8, 24, 168, or 720.

Request Body

{
  "themeMode": "dark",
  "language": "en",
  "notifications": {
    "emailNotifications": true,
    "pushNotifications": true,
    "weeklyDigest": true,
    "mentionAlerts": true
  }
}

Get Organization Settings

GET /v1/settings/org

Returns the organization’s settings. A single setting can be fetched with GET /v1/settings/org/:key.

Update Organization Settings

PUT /v1/settings/org

Updates organization settings in a single batch. Requires the org.manage_settings permission.

Request Body

{
  "settings": {
    "enforce_mfa": true,
    "invite_policy": "member_invite"
  }
}

Alert Rules

List Alert Rules

GET /v1/alert-rules

Returns the organization’s alert rules. The organization is taken from the authenticated session; no query parameters are required.

Create Alert Rule

POST /v1/alert-rules

Request Body

{
  "name": "High-priority task overdue",
  "event_type": "task.overdue",
  "description": "Notify leads when critical tasks slip",
  "conditions": {
    "priority": ["critical", "high"]
  },
  "channels": ["email", "in_app"]
}

The organization is taken from the authenticated session. If event_type is omitted, trigger_type is accepted as an alias. Do not send id, created_at, updated_at, or org_id in the request body; these are assigned by the server.

Response

A successful create returns the complete alert-rule record inside the standard envelope. New rules are enabled by default and, when channels is omitted, default to the in_app channel.

{
  "success": true,
  "data": {
    "id": "...",
    "org_id": "...",
    "name": "High-priority task overdue",
    "description": "Notify leads when critical tasks slip",
    "event_type": "task.overdue",
    "conditions": { "priority": ["critical", "high"] },
    "channels": ["email", "in_app"],
    "is_enabled": true,
    "created_by": "...",
    "created_at": "2026-04-12T15:30:00Z",
    "updated_at": "2026-04-12T15:30:00Z"
  }
}

Response Codes

Update / Delete Alert Rule

PUT /v1/alert-rules/:id
DELETE /v1/alert-rules/:id

These endpoints are reserved but not yet implemented; they currently return 501 Not Implemented. Editing and removing alert rules is coming soon.