openapi: 3.0.1
info:
  title: Notification APIs
  description: >-
    Notification APIs manage and deliver real-time alerts, push notifications,
    and user messages. They support multiple channels for timely communication
    between the system and users.
  version: 1.0.1
  contact:
    name: IVALT Support
    url: https://ivalt.com/support
    email: support@ivalt.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
tags:
  - name: NotificationApis
    description: Operations for sending alerts, push notifications, and messages to users.
paths:
  /send/global/notification:
    post:
      summary: Send global notification
      description: >-
        Sends a notification to a recipient identified by their mobile number.
        Used for OTPs, alerts, and global system notifications. The mobile
        number must follow E.164 format (e.g., +91XXXXXXXXXX).
      operationId: sendGlobalNotification
      tags:
        - NotificationApis
      parameters:
        - $ref: '#/components/parameters/AcceptHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GlobalNotificationRequest'
            examples:
              validRequest:
                summary: Valid request example
                value:
                  mobile: +9162839xxxxx
      responses:
        '200':
          description: Notification sent successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Send global notification
                    timestamp: '2025-09-22T09:35:00Z'
        '400':
          description: Invalid or missing mobile number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
  /send-auth-request-by-email:
    post:
      summary: Send authentication request by email
      description: >-
        Sends an authentication notification to a recipient via email for login
        verification or identity confirmation.
      operationId: sendAuthRequestByEmail
      tags:
        - NotificationApis
      parameters:
        - $ref: '#/components/parameters/AcceptHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailNotificationRequest'
            examples:
              validRequest:
                summary: Valid request example
                value:
                  email: user@ivalt.com
      responses:
        '200':
          description: Notification sent successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Send authentication request by email
                    timestamp: '2025-09-22T09:35:00Z'
        '400':
          description: Invalid or missing email address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
  /send/app-auth/notification:
    post:
      summary: Send app authentication notification
      description: >-
        Sends an authentication request from one mobile user to another —
        typically used in peer-to-peer or user-to-admin workflows.
      operationId: sendAppAuthNotification
      tags:
        - NotificationApis
      parameters:
        - $ref: '#/components/parameters/AcceptHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppAuthNotificationRequest'
            examples:
              validRequest:
                summary: Valid request example
                value:
                  request_to_mobile: +9162839xxxxx
                  request_from_mobile: +9178375xxxxx
      responses:
        '200':
          description: Notification sent successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    status: success
                    message: Send app authentication notification
                    timestamp: '2025-09-22T09:35:00Z'
        '400':
          description: Invalid or missing mobile numbers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Validation error
                  value:
                    status: error
                    message: Bad request - missing or invalid data
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  parameters:
    AcceptHeader:
      name: Accept
      in: header
      description: >-
        Optional. Indicates the response format. Defaults to `application/json`
        if not provided.
      required: false
      example: application/json
      schema:
        type: string
  schemas:
    GlobalNotificationRequest:
      type: object
      description: Request body for sending a global notification to a single recipient.
      properties:
        mobile:
          type: string
          description: The recipient's mobile number in E.164 format (e.g., +91XXXXXXXXXX).
          example: +9162839xxxxx
    EmailNotificationRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: Recipient's email address.
          example: user@ivalt.com
    AppAuthNotificationRequest:
      type: object
      required:
        - request_to_mobile
        - request_from_mobile
      properties:
        request_to_mobile:
          type: string
          description: Recipient’s mobile number (E.164 format).
          example: +9162839xxxxx
        request_from_mobile:
          type: string
          description: Sender’s mobile number (E.164 format).
          example: +9178375xxxxx
    SuccessResponse:
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: string
          enum:
            - success
          description: Indicates a successful request.
        message:
          type: string
          description: Summary of successful operation.
        timestamp:
          type: string
          format: date-time
          description: Server timestamp in UTC.
    ErrorResponse:
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: string
          enum:
            - error
          description: Indicates an error response.
        message:
          type: string
          description: Description of the error or validation failure.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key required in the `x-api-key` header.
servers:
  - url: https://dev.api.ivalt.com/admin/public/api
    description: Development server
security:
  - ApiKeyAuth: []
