mammoth-io Notifications API

openapi: 3.2.0
info:
  title: Mammoth Io Notifications API
  version: 0.1.0
  contact:
    name: Mammoth Analytics
    url: https://mammoth.io
    email: support@mammoth.io
  description: 'Operations tagged Notifications across 2 of this provider''s published API definitions: app.mammoth.io-openapi.json, mammoth-io-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: /api/v2
security:
- bearerAuth: []
- apiKey: []
  apiSecret: []
  workspaceId: []
tags:
- name: Notifications
paths:
  /notifications/{notification_id}:
    delete:
      tags:
      - Notifications
      summary: Delete notification
      description: Delete a single notification by ID.
      operationId: DeleteNotification
      parameters:
      - name: notification_id
        in: path
        schema:
          type: integer
          title: Notification ID
          description: Notification identifier
          examples:
          - 36
        description: Notification identifier
        required: true
        deprecated: false
        examples:
          notification_id-example-1:
            summary: Sample notification id
            value: 36
      responses:
        '204':
          description: Request fulfilled, nothing follows
          headers: {}
        '400':
          description: Bad Request
        '200':
          description: Success
        '401':
          description: Unauthorized
      deprecated: false
    patch:
      tags:
      - Notifications
      summary: Edit notification
      description: Update a single notification. Supports read status, pop-up status, dismissal, deletion and persistence.
      operationId: EditNotification
      parameters:
      - name: notification_id
        in: path
        schema:
          type: integer
          title: Notification ID
          description: Notification identifier
          examples:
          - 36
        description: Notification identifier
        required: true
        deprecated: false
        examples:
          notification_id-example-1:
            summary: Sample notification id
            value: 36
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationsPatchRequest'
        required: true
      responses:
        '200':
          description: Success
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      deprecated: false
    servers:
    - url: /api/v2
  /notifications:
    get:
      tags:
      - Notifications
      summary: List notifications
      description: Returns notifications for the user's workspaces, with optional filters for status, read state, scope, and time range.
      operationId: GetAllNotifications
      parameters:
      - name: fields
        in: query
        schema:
          oneOf:
          - type: string
            default: __standard
          - type: 'null'
          title: Fields
          description: Fields to be returned in a comma-separated format may include id, workspace_id, details
          default: __standard
          examples:
          - id,workspace_id,details
          - __full
          - __standard
          - __min
        description: Fields to be returned in a comma-separated format may include id, workspace_id, details
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
        examples:
          fields-example-1:
            summary: Returns only the fields specified in the comma-separated format
            value: id,workspace_id,details
          fields-example-2:
            summary: Return full representation of notifications. Full representation includes id,workspace_id,last_updated_at,project_id,details,status,type,data_updated_at,is_read,scope,scope_id,expires_at
            value: __full
          fields-example-3:
            summary: Return standard representation of notifications. standard representation includes id,workspace_id,last_updated_at,project_id,details,status,type,data_updated_at,is_read,scope,scope_id
            value: __standard
          fields-example-4:
            summary: Return minimal representation of notifications. Minimal representation includes id,workspace_id,last_updated_at
            value: __min
      - name: workspace_id
        in: query
        schema:
          oneOf:
          - type: integer
            minimum: 1.0
            title: Workspace ID
            description: Workspace refers to a collection of projects. Workspace ID is unique identifier for workspace.
            examples:
            - 4
          - type: 'null'
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
      - name: project_id
        in: query
        schema:
          oneOf:
          - type: integer
            minimum: 1.0
            title: Project ID
            description: Project ID of the workspace
            examples:
            - 4
          - type: 'null'
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
      - name: last_updated_at__gte
        in: query
        schema:
          oneOf:
          - type: string
          - type: 'null'
          title: Last Updated GTE
          description: 'Filter notifications updated greater than or equal to the given timestamp. Format: ISO 8601 (e.g. ''2023-01-01T00:00:00Z'')'
          examples:
          - '2023-01-01T00:00:00Z'
        description: 'Filter notifications updated greater than or equal to the given timestamp. Format: ISO 8601 (e.g. ''2023-01-01T00:00:00Z'')'
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
        examples:
          last_updated_at__gte-example-1:
            summary: Filter notifications updated on or after January 1, 2023
            value: '2023-01-01T00:00:00Z'
      - name: status
        in: query
        schema:
          oneOf:
          - type: string
          - type: 'null'
          title: Notification Status
          description: Filter notifications by status
          examples:
          - completed
        description: Filter notifications by status
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
        examples:
          status-example-1:
            summary: Filter notifications with completed status
            value: completed
      - name: is_read
        in: query
        schema:
          oneOf:
          - type: boolean
          - type: 'null'
          title: Is Read
          description: Filter notifications read status
          examples:
          - true
        description: Filter notifications read status
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
        examples:
          is_read-example-1:
            summary: Filter notifications read status
            value: true
      - name: notification_scope
        in: query
        schema:
          oneOf:
          - $ref: '#/components/schemas/NotificationScope'
          - type: 'null'
          title: Notification Scope
          description: Filter notifications by scope
          examples:
          - workspace
        description: Filter notifications by scope
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
        examples:
          notification_scope-example-1:
            summary: Filter notifications with workspace scope
            value: workspace
      - name: limit
        in: query
        schema:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Limit
          description: Max number of result to return
          default: 50
          examples:
          - 10
        description: Max number of result to return
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
        examples:
          limit-example-1:
            summary: Limit returned result count to 10
            value: 10
      - name: offset
        in: query
        schema:
          type: integer
          minimum: 0.0
          title: Offset
          description: Distance from the beginning of the list of results
          default: 0
          examples:
          - 10
        description: Distance from the beginning of the list of results
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
        examples:
          offset-example-1:
            summary: Start from 10th result
            value: 10
      - name: sort
        in: query
        schema:
          type: string
          title: Sort by the given fields
          description: Returned results are sorted by the combination of the given fields.
          default: (id:asc)
          examples:
          - (id:asc)
          - (id:asc),(name:asc)
        description: Returned results are sorted by the combination of the given fields.
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
        examples:
          sort-example-1:
            summary: Sort by <Resource>.id asc
            value: (id:asc)
          sort-example-2:
            summary: Sort by <Resource>_id and <Resource>_name asc
            value: (id:asc),(name:asc)
      responses:
        '200':
          description: List of notifications
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationListResponse'
        '400':
          description: Bad Request
        '403':
          description: Request forbidden -- authorization will not help
          content:
            application/json:
              schema:
                properties:
                  status_code:
                    type: integer
                  detail:
                    type: string
                  extra:
                    additionalProperties: {}
                    type:
                    - 'null'
                    - object
                    - array
                type: object
                required:
                - detail
                - status_code
                description: Authorization Exception
                examples:
                - status_code: 403
                  detail: Forbidden
                  extra: {}
        '401':
          description: Unauthorized
      deprecated: false
    delete:
      tags:
      - Notifications
      summary: Delete notifications (batch)
      description: Batch deletion of notifications. Supports deleting by explicit IDs (ids) or by time threshold (last_updated_at__lt), optionally filtered by read state.
      operationId: DeleteNotifications
      parameters:
      - name: workspace_id
        in: query
        schema:
          type: integer
          minimum: 1.0
          title: Workspace ID
          description: Workspace refers to a collection of projects. Workspace ID is unique identifier for workspace.
          default: 2
          examples:
          - 4
        description: Workspace refers to a collection of projects. Workspace ID is unique identifier for workspace.
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
        examples:
          workspace_id-example-1:
            summary: Sample workspace ID
            value: 4
      - name: ids
        in: query
        schema:
          oneOf:
          - type: string
          - type: 'null'
          title: Notification IDs
          description: Comma-separated list of notification IDs to delete.
          examples:
          - 1,2,3
        description: Comma-separated list of notification IDs to delete.
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
        examples:
          ids-example-1:
            summary: Delete notifications with IDs 1, 2 and 3
            value: 1,2,3
      - name: last_updated_at__lt
        in: query
        schema:
          oneOf:
          - type: string
          - type: 'null'
          title: Last Updated LT
          description: 'Delete notifications last updated before this timestamp. Format: ISO 8601 (e.g. ''2024-01-01T00:00:00Z''). Defaults to deleting only read notifications unless is_read is specified.'
          examples:
          - '2024-01-01T00:00:00Z'
        description: 'Delete notifications last updated before this timestamp. Format: ISO 8601 (e.g. ''2024-01-01T00:00:00Z''). Defaults to deleting only read notifications unless is_read is specified.'
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
        examples:
          last_updated_at__lt-example-1:
            summary: Delete notifications updated before January 1, 2024
            value: '2024-01-01T00:00:00Z'
      - name: is_read
        in: query
        schema:
          oneOf:
          - type: boolean
          - type: 'null'
          title: Is Read
          description: Filter notifications read status
          examples:
          - true
        description: Filter notifications read status
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
        examples:
          is_read-example-1:
            summary: Filter notifications read status
            value: true
      responses:
        '204':
          description: Request fulfilled, nothing follows
          headers: {}
        '400':
          description: Bad Request
        '200':
          description: Success
        '401':
          description: Unauthorized
      deprecated: false
    patch:
      tags:
      - Notifications
      summary: Edit notifications (batch)
      description: Batch operations for notifications. Currently supports marking multiple notifications read.
      operationId: EditNotifications
      parameters:
      - name: workspace_id
        in: query
        schema:
          type: integer
          minimum: 1.0
          title: Workspace ID
          description: Workspace refers to a collection of projects. Workspace ID is unique identifier for workspace.
          default: 2
          examples:
          - 4
        description: Workspace refers to a collection of projects. Workspace ID is unique identifier for workspace.
        required: false
        deprecated: false
        allowEmptyValue: false
        allowReserved: false
        examples:
          workspace_id-example-1:
            summary: Sample workspace ID
            value: 4
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationsPatchRequest'
        required: true
      responses:
        '200':
          description: Success
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
      deprecated: false
    servers:
    - url: /api/v2
components:
  schemas:
    PatchOp:
      type: string
      enum:
      - replace
      title: PatchOp
      description: Supported operation
      examples:
      - value: replace
    NotificationScope:
      type: string
      enum:
      - workspace
      - project
      - user
      title: NotificationScope
      description: '

        Notifications can be scoped in these

        types.

        '
    NotificationPatchItem:
      properties:
        op:
          $ref: '#/components/schemas/PatchOp'
        path:
          $ref: '#/components/schemas/NotificationPatchPath'
        value:
          oneOf:
          - type: boolean
          - type: string
          title: Value
          description: Value for the patch operation
      type: object
      required:
      - op
      - path
      - value
      title: NotificationPatchItem
    NotificationListResponse:
      properties:
        notifications:
          items:
            $ref: '#/components/schemas/NotificationSchema'
          type: array
      type: object
      required:
      - notifications
      title: NotificationListResponse
    NotificationPatchPath:
      type: string
      enum:
      - isReadMultiple
      - isReadMultipleIds
      - isRead
      - hasPoppedUp
      - isDismissed
      - isDeleted
      - markPersistent
      title: NotificationPatchPath
      description: Field to update
      examples:
      - value: isRead
    NotificationSchema:
      properties:
        id:
          oneOf:
          - type: integer
          - type: 'null'
          title: Notification ID
          description: Unique identifier of the notification
        workspace_id:
          oneOf:
          - type: integer
          - type: 'null'
          title: Workspace ID
          description: Workspace the notification belongs to
        last_updated_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Updated At
          description: Timestamp of the last update to the notification
        project_id:
          oneOf:
          - type: integer
          - type: 'null'
          title: Project ID
          description: Project the notification is associated with
        details:
          oneOf:
          - additionalProperties: {}
            type: object
          - type: 'null'
          title: Details
          description: Notification payload details such as title, body, and contextual metadata
        status:
          oneOf:
          - $ref: '#/components/schemas/NotificationStatus'
          - type: 'null'
          title: Status
          description: Lifecycle status of the notification (e.g. inited, archived)
        type:
          oneOf:
          - $ref: '#/components/schemas/NotificationTypes'
          - type: 'null'
          title: Type
          description: Notification type indicating its category (e.g. transient, persistent)
        data_updated_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Data Updated At
          description: Timestamp when the underlying data that triggered the notification was last updated
        is_read:
          oneOf:
          - type: boolean
          - type: 'null'
          title: Is Read
          description: Whether the notification has been read by the user
        scope:
          oneOf:
          - $ref: '#/components/schemas/NotificationScope'
          - type: 'null'
          title: Scope
          description: Scope of the notification indicating the resource type it relates to
        scope_id:
          oneOf:
          - type: integer
          - type: 'null'
          title: Scope ID
          description: Identifier of the scoped resource; -1 indicates no specific resource
        expires_at:
          oneOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
          description: Timestamp after which the notification is considered expired
      type: object
      required: []
      title: NotificationSchema
    NotificationsPatchRequest:
      properties:
        patch:
          items:
            $ref: '#/components/schemas/NotificationPatchItem'
          type: array
          title: Patch
          description: Patch operations
          examples:
          - summary: Sample patch to mark notification as read
            value:
              patch:
              - op: replace
                path: isRead
                value: true
      type: object
      required:
      - patch
      title: NotificationsPatchRequest
      description: Patch operations for notifications
      examples:
      - patch:
        - op: replace
          path: isRead
          value: true
    NotificationTypes:
      type: string
      enum:
      - TRANSIENT
      - REQUIRES_USER_DISMISSAL
      - WARNING_NOTICE
      - CONFIRMATION
      title: NotificationTypes
    NotificationStatus:
      type: string
      enum:
      - inited
      - processing
      - dismissed
      - deleted
      - completed
      - error
      title: NotificationStatus
  securitySchemes:
    bearerAuth:
      type: http
      description: 'Primary credential. Authorization: Bearer mm_<token>. The token is issued server-side and shown once at creation.'
      scheme: bearer
    apiKey:
      type: apiKey
      description: Deprecated — use bearerAuth.
      name: X-API-KEY
      in: header
    apiSecret:
      type: apiKey
      description: Deprecated — use bearerAuth.
      name: X-API-SECRET
      in: header
    workspaceId:
      type: apiKey
      description: Required with X-API-KEY and X-API-SECRET. Deprecated with them — use bearerAuth.
      name: X-WORKSPACE-ID
      in: header
x-refined-from:
- app.mammoth.io-openapi.json
- mammoth-io-openapi.json