Nex Notifications API

openapi: 3.0.0
info:
  description: REST API for accessing and managing your Nex data. Generate API keys from the Nex web UI and use them to authenticate requests.
  title: Nex Developer AI Lists Notifications API
  contact: {}
  version: '1.0'
servers:
- url: https://app.nex.ai/api/developers
tags:
- name: Notifications
paths:
  /v1/notifications/feed:
    get:
      security:
      - ApiKeyAuth: []
      description: Returns recent context alerts generated by the server-side notification system. Use the `since` parameter for incremental polling.
      tags:
      - Notifications
      summary: Get Notification Feed
      operationId: getNotificationFeed
      parameters:
      - description: 'Maximum number of notifications to return (default: 20, max: 50)'
        name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
      - description: Only return notifications after this ISO 8601 timestamp (for incremental polling)
        name: since
        in: query
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: List of notification feed items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/developer.NotificationFeedResponse'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
  /v1/notifications/preferences:
    get:
      security:
      - ApiKeyAuth: []
      description: Returns the current notification preferences including polling frequency, enabled notification types, and digest settings.
      tags:
      - Notifications
      summary: Get Notification Preferences
      operationId: getNotificationPreferences
      responses:
        '200':
          description: Current notification preferences
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/developer.NotificationPreferencesResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
    patch:
      security:
      - ApiKeyAuth: []
      description: Update notification polling frequency, enabled types, or digest settings. All fields are optional.
      tags:
      - Notifications
      summary: Update Notification Preferences
      operationId: updateNotificationPreferences
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/developer.UpdateNotificationPreferencesRequest'
        description: Notification preferences to update
        required: true
      responses:
        '200':
          description: Updated notification preferences
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/developer.NotificationPreferencesResponse'
        '400':
          description: Bad request - Invalid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
  /v1/notifications/custom:
    get:
      security:
      - ApiKeyAuth: []
      description: List all custom AI notification rules configured for the authenticated user.
      tags:
      - Notifications
      summary: List Custom Notification Rules
      operationId: listCustomNotificationRules
      responses:
        '200':
          description: List of custom notification rules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/developer.ListCustomNotificationRulesResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
    post:
      security:
      - ApiKeyAuth: []
      description: Create a new AI-powered notification rule. Describe what you want to be notified about in natural language.
      tags:
      - Notifications
      summary: Create Custom Notification Rule
      operationId: createCustomNotificationRule
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/developer.CreateCustomNotificationRuleRequest'
        description: Custom notification rule to create
        required: true
      responses:
        '200':
          description: Created custom notification rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/developer.CustomNotificationRuleResponse'
        '400':
          description: Bad request - Invalid data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
  /v1/notifications/custom/{id}:
    get:
      security:
      - ApiKeyAuth: []
      description: Get a specific custom notification rule by ID.
      tags:
      - Notifications
      summary: Get Custom Notification Rule
      operationId: getCustomNotificationRule
      parameters:
      - description: Custom notification rule ID
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Custom notification rule details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/developer.CustomNotificationRuleResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '404':
          description: Custom notification rule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
    delete:
      security:
      - ApiKeyAuth: []
      description: Delete a custom notification rule. This action cannot be undone.
      tags:
      - Notifications
      summary: Delete Custom Notification Rule
      operationId: deleteCustomNotificationRule
      parameters:
      - description: Custom notification rule ID
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully deleted
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '404':
          description: Custom notification rule not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/httpx.APIError'
components:
  schemas:
    httpx.APIError:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    developer.NotificationFeedItem:
      type: object
      properties:
        id:
          type: string
          description: Unique notification ID
        type:
          type: string
          description: Notification type (e.g., 'context_alert', 'digest')
        status:
          type: string
          description: Notification status (e.g., 'unread', 'read')
        alert_time:
          type: string
          format: date-time
          description: When the alert condition was detected
        sent_at:
          type: string
          format: date-time
          description: When the notification was sent
        content:
          type: object
          description: Notification content payload
          properties:
            important_items:
              type: array
              description: List of important items flagged by the notification system
              items:
                type: object
            entity_changes:
              type: array
              description: List of entity changes that triggered the notification
              items:
                type: object
    developer.NotificationPreferencesResponse:
      type: object
      properties:
        frequency_minutes:
          type: integer
          description: How often the notification system polls for new alerts (in minutes)
        enabled_types:
          type: array
          description: List of enabled notification types
          items:
            type: string
        digest_enabled:
          type: boolean
          description: Whether digest notifications are enabled
    developer.UpdateNotificationPreferencesRequest:
      type: object
      properties:
        frequency_minutes:
          type: integer
          description: How often the notification system polls for new alerts (in minutes)
        enabled_types:
          type: array
          description: List of notification types to enable
          items:
            type: string
        digest_enabled:
          type: boolean
          description: Whether to enable digest notifications
    developer.NotificationFeedResponse:
      type: object
      properties:
        items:
          type: array
          description: List of notification feed items
          items:
            $ref: '#/components/schemas/developer.NotificationFeedItem'
    developer.ListCustomNotificationRulesResponse:
      type: object
      properties:
        rules:
          type: array
          description: List of custom notification rules
          items:
            $ref: '#/components/schemas/developer.CustomNotificationRuleResponse'
    developer.CustomNotificationRuleResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique rule ID
        name:
          type: string
          description: Human-readable rule name
        prompt:
          type: string
          description: The natural language prompt describing the notification condition
        is_enabled:
          type: boolean
          description: Whether the rule is currently active
        schedule:
          type: string
          description: Cron-style schedule for rule evaluation
        created_at:
          type: string
          format: date-time
          description: When the rule was created
    developer.CreateCustomNotificationRuleRequest:
      type: object
      required:
      - description
      properties:
        description:
          type: string
          description: Natural language description of what you want to be notified about
  securitySchemes:
    ApiKeyAuth:
      description: 'API key for authentication (format: "Bearer YOUR_API_KEY")'
      type: apiKey
      name: Authorization
      in: header