> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tetherai.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Get notifications for the logged-in user

> Return the authenticated user's in-app notifications, transformed for the bell-tray UI. Status (`read`/`unread`) is overlaid from the per-user `User.notifications[].status` map.



## OpenAPI

````yaml /api-reference/openapi.yaml get /api/notifications
openapi: 3.0.3
info:
  title: Tether Relay and Tether API
  version: 1.0.0
  description: >-
    Route-derived OpenAPI contract generated from tether-relay backend sources.
    Regenerate with scripts/sync-openapi-from-backend.mjs.
servers:
  - url: https://your-instance.example.com
    description: Production
  - url: http://localhost:2212
    description: Local API service
security: []
tags:
  - name: AI
  - name: Applications
  - name: Approval
  - name: Auth
  - name: Automations
  - name: Calls
  - name: Campaigns
  - name: Contact Analytics
  - name: Contact Metrics
  - name: Contact Notes
  - name: Contacts
  - name: Conversation Monitor
  - name: Conversations
  - name: Departments
  - name: Email
  - name: Escalation Dashboard
  - name: Event Logs
  - name: Google Sheets
  - name: Marketplace
  - name: Messages
  - name: Notification Sounds
  - name: Notifications
  - name: Org Snapshots
  - name: Organizations
  - name: Outreach
  - name: Outreach Metrics
  - name: Outreach Sources
  - name: Pipelines
  - name: Processes
  - name: Prompts
  - name: Reminders
  - name: Sms
  - name: Templates
  - name: Traces
  - name: Training
  - name: Upload
  - name: User Snapshots
  - name: Users
  - name: Vertical
  - name: Webchats
  - name: Webhook
paths:
  /api/notifications:
    get:
      tags:
        - Notification
      summary: Get notifications for the logged-in user
      description: >-
        Return the authenticated user's in-app notifications, transformed for
        the bell-tray UI. Status (`read`/`unread`) is overlaid from the per-user
        `User.notifications[].status` map.
      operationId: get_notifications
      responses:
        '200':
          description: Notifications list (raw array, not enveloped)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationListResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    NotificationListResponse:
      type: array
      description: >-
        Raw array — the GET handler returns the list directly without a `{
        success, data }` envelope. If the user has no notifications the array is
        empty.
      items:
        $ref: '#/components/schemas/NotificationListItem'
      example:
        - id: 66e0a0b0c0d0e0f0a0b0c0d0
          title: Cory Tan mentioned you
          message: '@alice please review this lead'
          category: mention
          createdAt: '2026-05-18T14:30:00.000Z'
          status: unread
          notificationType: mention
          contactId: 65c2d0e0f0a0b0c0d0e0f0a0
          contactName: Jane Doe
          phoneNumber: '+14155550123'
    NotificationErrorResponse:
      type: object
      description: >-
        Error envelope returned by notification endpoints. 500 paths return `{
        error }`; mention-send failures may also include `details`.
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: string
        details:
          type: string
      additionalProperties: true
      example:
        success: false
        error: Notification not found
    NotificationListItem:
      type: object
      description: >-
        Transformed notification row returned to the UI. Built from
        `Notification` doc + per-user `status` from `User.notifications`.
      properties:
        id:
          type: string
        title:
          type: string
        message:
          type: string
        category:
          type: string
        createdAt:
          type: string
          format: date-time
        status:
          type: string
          description: >-
            Per-user status from `User.notifications[].status` (defaults to
            `unread`).
        notificationType:
          type: string
          description: e.g. `mention`, `assignment`, `other`.
        contactId:
          type: string
          nullable: true
        contactName:
          type: string
          nullable: true
        phoneNumber:
          type: string
          nullable: true
        userId:
          type: string
          nullable: true
        mentionedBy:
          type: string
          nullable: true
        campaignId:
          type: string
          nullable: true
        messageId:
          type: string
          nullable: true
      required:
        - id
      additionalProperties: true
      example:
        id: 66e0a0b0c0d0e0f0a0b0c0d0
        title: Cory Tan mentioned you
        message: '@alice please review this lead'
        category: mention
        createdAt: '2026-05-18T14:30:00.000Z'
        status: unread
        notificationType: mention
        contactId: 65c2d0e0f0a0b0c0d0e0f0a0
        contactName: Jane Doe
        phoneNumber: '+14155550123'
        mentionedBy: 65b1f0a2c3d4e5f6a7b8c9d3
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````