Clarifeye Notifications API

openapi: 3.2.0
info:
  title: Clarifeye Platform Notifications API
  description: REST API for the Clarifeye Platform - Document intelligence and AI-powered analysis.
  version: 1.0.0
  contact:
    name: Clarifeye Support
servers:
- url: https://eu.app.clarifeye.ai/api/v1
  description: EU
- url: https://us.app.clarifeye.ai/api/v1
  description: US
security:
- BearerAuth: []
- TokenAuth: []
tags:
- name: Notifications
  description: Manage project-scoped notifications for users
paths:
  /projects/{project_id}/notifications/:
    get:
      tags:
      - Notifications
      summary: List project notifications
      description: 'List notifications for the effective user (authenticated user or impersonated user).


        **Filtering:**

        - Only PROJECT-scoped notifications are returned (not account-level)

        - Returns all unread notifications plus read notifications from the last 7 days

        - Optionally filter by status using the `status` query parameter


        **Impersonation:**

        When using the `X-Impersonate-Email` header, returns notifications for the target user

        instead of the authenticated user.'
      operationId: listProjectNotifications
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ImpersonateEmail'
      - name: status
        in: query
        description: Filter by notification status
        schema:
          $ref: '#/components/schemas/NotificationStatus'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedResponse'
                - type: object
                  properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/ProjectScopedNotification'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/notifications/{notification_id}/:
    get:
      tags:
      - Notifications
      summary: Retrieve a notification
      description: 'Retrieve details of a single notification for the effective user.


        **Impersonation:**

        When using the `X-Impersonate-Email` header, retrieves the notification for the target user.'
      operationId: getProjectNotification
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/NotificationId'
      - $ref: '#/components/parameters/ImpersonateEmail'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectScopedNotification'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Notifications
      summary: Delete a notification
      description: 'Delete a single notification for the effective user.


        **Impersonation:**

        When using the `X-Impersonate-Email` header, deletes the notification for the target user.'
      operationId: deleteProjectNotification
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/NotificationId'
      - $ref: '#/components/parameters/ImpersonateEmail'
      responses:
        '204':
          description: Notification deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/notifications/{notification_id}/mark-as-read/:
    post:
      tags:
      - Notifications
      summary: Mark notification as read
      description: 'Mark a single notification as read for the effective user.


        **Impersonation:**

        When using the `X-Impersonate-Email` header, marks the notification as read for the target user.'
      operationId: markNotificationAsRead
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/NotificationId'
      - $ref: '#/components/parameters/ImpersonateEmail'
      responses:
        '200':
          description: Notification marked as read
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectScopedNotification'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/notifications/{notification_id}/mark-as-unread/:
    post:
      tags:
      - Notifications
      summary: Mark notification as unread
      description: 'Mark a single notification as unread for the effective user.


        **Impersonation:**

        When using the `X-Impersonate-Email` header, marks the notification as unread for the target user.'
      operationId: markNotificationAsUnread
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/NotificationId'
      - $ref: '#/components/parameters/ImpersonateEmail'
      responses:
        '200':
          description: Notification marked as unread
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectScopedNotification'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/notifications/mark-all-as-read/:
    post:
      tags:
      - Notifications
      summary: Mark all notifications as read
      description: 'Mark all unread project notifications as read for the effective user.


        **Impersonation:**

        When using the `X-Impersonate-Email` header, marks all notifications as read for the target user.'
      operationId: markAllNotificationsAsRead
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ImpersonateEmail'
      responses:
        '200':
          description: All notifications marked as read
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationBulkActionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_id}/notifications/delete-read/:
    post:
      tags:
      - Notifications
      summary: Delete all read notifications
      description: 'Delete all read project notifications for the effective user.


        **Impersonation:**

        When using the `X-Impersonate-Email` header, deletes all read notifications for the target user.'
      operationId: deleteReadNotifications
      parameters:
      - $ref: '#/components/parameters/ProjectId'
      - $ref: '#/components/parameters/ImpersonateEmail'
      responses:
        '200':
          description: All read notifications deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationBulkActionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    Limit:
      name: limit
      in: query
      description: Maximum number of results per page
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 1000
    Offset:
      name: offset
      in: query
      description: Number of results to skip for pagination
      schema:
        type: integer
        default: 0
        minimum: 0
    ProjectId:
      name: project_id
      in: path
      required: true
      description: UUID of the project
      schema:
        type: string
        format: uuid
    ImpersonateEmail:
      name: X-Impersonate-Email
      in: header
      required: false
      description: 'Email of the user to impersonate. Requires `CAN_IMPERSONATE_OTHER_USERS` permission.

        If the target user is not found or does not have access to the project, the request

        proceeds as the authenticated user. Contact Clarifeye to enable this permission.

        '
      schema:
        type: string
        format: email
    NotificationId:
      name: notification_id
      in: path
      required: true
      description: UUID of the notification
      schema:
        type: string
        format: uuid
  schemas:
    NotificationBase:
      type: object
      description: Base notification properties shared by all notification types
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the notification
        created_at:
          type: string
          format: date-time
          description: When the notification was created
        updated_at:
          type: string
          format: date-time
          description: When the notification was last updated
        user:
          type: string
          format: uuid
          description: ID of the user this notification belongs to
        status:
          $ref: '#/components/schemas/NotificationStatus'
        access_level:
          $ref: '#/components/schemas/NotificationAccessLevel'
        title:
          type: string
          description: Notification title
          example: Document processing completed
        message:
          type: string
          description: Notification message body
          example: Your document 'Q4 Report.pdf' has been processed successfully.
        notification_type:
          type: string
          description: Type/category of the notification
          example: document_processed
        actions:
          type: object
          description: 'Optional actions that can be taken from the notification.

            Structure may include:

            - `primary`: Primary action with `label` and `type`

            - `secondary`: Array of secondary actions

            '
          example:
            primary:
              label: View Document
              type: navigate
              url: /documents/123
        read_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the notification was marked as read (null if unread)
        source_object_type:
          type: string
          description: Type of the source object that triggered this notification
          example: document
        source_object_id:
          type: string
          description: ID of the source object that triggered this notification
          example: 550e8400-e29b-41d4-a716-446655440000
        relative_time:
          type: string
          description: Human-readable relative time (e.g., "2 minutes ago", "Yesterday")
          example: 2 hours ago
        absolute_time:
          type: string
          format: date-time
          description: ISO format absolute timestamp
    NotificationAccessLevel:
      type: string
      enum:
      - admin
      - viewer
      description: '- `admin`: Notification visible only to project admins

        - `viewer`: Notification visible to all project members

        '
    NotificationStatus:
      type: string
      enum:
      - unread
      - read
      description: '- `unread`: Notification has not been read

        - `read`: Notification has been read

        '
    PaginatedResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total number of results
        next:
          type:
          - string
          - 'null'
          format: uri
          description: URL to next page of results
        previous:
          type:
          - string
          - 'null'
          format: uri
          description: URL to previous page of results
        results:
          type: array
          items: {}
    NotificationBulkActionResponse:
      type: object
      properties:
        message:
          type: string
          description: Human-readable message describing the action taken
          example: Marked 5 notifications as read
        count:
          type: integer
          description: Number of notifications affected by the action
          example: 5
    ProjectScopedNotification:
      description: 'A project-scoped notification. Returned by project notification endpoints.

        The `scope` is always "project" and `project` is always a non-null UUID.

        '
      allOf:
      - $ref: '#/components/schemas/NotificationBase'
      - type: object
        required:
        - scope
        - project
        properties:
          scope:
            type: string
            enum:
            - project
            description: Always "project" for project-scoped notifications
          project:
            type: string
            format: uuid
            description: UUID of the project this notification belongs to (always non-null)
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      example:
        error: User not found
  responses:
    NotFound:
      description: Not found - resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not found.
    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: You do not have permission to perform this action.
    Unauthorized:
      description: Unauthorized - missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Authentication credentials were not provided.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Use Authorization: Bearer <token>'
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Authorization: Token <token>'