openapi: 3.1.1
info:
  title: Korrero Notification API
  description: |
    Korrero (kōrero from Māori: tell, say, speak, read, talk, address) is a notification system API.
    
    This API allows you to:
    - Fetch notifications for your project using API keys
    - Track user interactions with notifications
    - Send enhanced tracking data with custom metadata
    
    ## Authentication

    The notifications endpoint requires authentication via API key. Include your project API key in the URL path.

    Tracking endpoints are publicly accessible and do not require authentication.
    
    ## Rate Limiting

    All endpoints are rate limited to 1000 requests per minute per IP address to prevent abuse. If you exceed this limit, you'll receive a 429 Too Many Requests response.
    
    ## Base URL
    
    All API requests should be made to: `https://api.korrero.com/api/v1/public`
  version: 1.0.0
  contact:
    name: Korrero Team
    email: support@korrero.com
  license:
    name: Terms of Service
    url: https://korrero.com/legal/terms-conditions

servers:
  - url: https://api.korrero.com/api/v1/public
    description: Main Server
paths:
  /{apiKey}/notifications:
    get:
      summary: Get notifications by API key
      description: |
        Retrieves notifications for the project associated with the provided API key.
        
        **Filtering Behavior:**
        - Always returns PUBLISHED notifications only
        - Time filtering based on API key settings:
          - **Current notifications**: Active now (startDate ≤ now ≤ endDate) - always included
          - **Past notifications**: Only if `showPast` setting is enabled
          - **Future notifications**: Only if `showFuture` setting is enabled
        
        **Ordering & Limits:**
        - Results ordered by API key `orderBy` setting (default: createdAt_desc)
        - Limited by 1000 last notifications.
        
      operationId: getNotificationsByApiKey
      tags:
        - Notifications
      parameters:
        - name: apiKey
          in: path
          required: true
          description: Project API key (32-64 character string)
          schema:
            type: string
            pattern: '^[a-zA-Z0-9]{32,64}$'
          example: abc123def456ghi789jkl012mno345pqr678stu901vwx234yz
      responses:
        '200':
          description: Successfully retrieved notifications
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PublicNotification'
              examples:
                success:
                  summary: Successful response with notifications
                  value:
                    - id: "notif_abc123"
                      message: "Welcome to our platform!"
                      image: "https://api.korrero.com/uploads/banner.jpg"
                      action:
                        type: "LINK"
                        data:
                          url: "https://example.com/welcome"
                          target: "_blank"
                      preset: "default"
                      startDate: "2024-01-01T00:00:00.000Z"
                      endDate: "2024-12-31T23:59:59.000Z"
                    - id: "notif_def456"
                      message: "New feature available!"
                      image: null
                      action:
                        type: "NO_ACTION"
                        data: null
                      preset: "minimal"
                      startDate: "2024-01-15T00:00:00.000Z"
                      endDate: null
        '401':
          description: Unauthorized - missing API key in path
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: "API key is required"
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /track/{notificationId}:
    post:
      summary: Track notification interaction (Simple)
      description: |
        Track a simple interaction with a notification. This is the simple tracking endpoint
        that accepts basic interaction types.
        
        Use this for simple impression and click tracking without additional metadata.
        Server automatically adds timestamp for temporal tracking.
        
        **Returns 204 No Content** on success (no response body).
      operationId: trackNotificationInteraction
      tags:
        - Tracking
      parameters:
        - name: notificationId
          in: path
          required: true
          description: Notification ID to track interaction for
          schema:
            type: string
            pattern: '^[a-zA-Z0-9_-]+$'
          example: "notif_abc123"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum: [impression, click]
                  description: Type of interaction to track (only impression and click supported)
              examples:
                impression:
                  summary: Impression tracking
                  value:
                    type: "impression"
                click:
                  summary: Click tracking
                  value:
                    type: "click"
      responses:
        '204':
          description: Interaction tracked successfully (no content returned)
        '400':
          description: Bad request - invalid interaction type
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "Invalid interaction type"
        '404':
          description: Notification not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
              example:
                message: "Notification not found"
                code: "NOTIFICATION_NOT_FOUND"
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "Internal server error"

  /track/{notificationId}/enhanced:
    post:
      summary: Track notification interaction (Enhanced)
      description: |
        Track an enhanced interaction with a notification, including custom metadata
        and detailed user context.

        This endpoint is publicly accessible and allows you to send rich tracking data
        for advanced analytics and insights.

        **Returns 204 No Content** on success (no response body).
      operationId: trackNotificationInteractionEnhanced
      tags:
        - Tracking
      parameters:
        - name: notificationId
          in: path
          required: true
          description: Notification ID to track interaction for
          schema:
            type: string
            pattern: '^[a-zA-Z0-9_-]+$'
          example: "notif_abc123"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum: [impression, click, conversion]
                  description: Type of interaction to track (NOTE - "dismiss" is not supported)
                timestamp:
                  type: string
                  format: date-time
                  description: When the interaction occurred (ISO 8601) - optional, server will use current time if not provided
                metadata:
                  type: object
                  description: Custom metadata for the interaction
                  additionalProperties: true
              examples:
                click:
                  summary: Click tracking with metadata
                  value:
                    type: "click"
                    timestamp: "2024-01-15T14:30:00Z"
                    metadata:
                      source: "homepage_banner"
                      campaign: "spring_sale_2024"
                      customField: "value123"
                impression:
                  summary: Simple impression tracking
                  value:
                    type: "impression"
                conversion:
                  summary: Conversion tracking
                  value:
                    type: "conversion"
                    metadata:
                      conversionValue: 99.99
                      conversionType: "purchase"
      responses:
        '204':
          description: Enhanced interaction tracked successfully (no content returned)
        '400':
          description: Bad request - invalid interaction type or missing required fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "Invalid interaction type"
        '404':
          description: Notification not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  code:
                    type: string
              example:
                message: "Notification not found"
                code: "NOTIFICATION_NOT_FOUND"
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: "Internal server error"

components:
  schemas:
    PublicNotification:
      type: object
      description: Public API notification format - simplified for external consumption
      required:
        - id
        - message
        - action
        - preset
      properties:
        id:
          type: string
          description: Unique notification identifier
          example: "notif_abc123"
        message:
          type: string
          description: The notification message content (may contain HTML/rich text)
          example: "Welcome to our platform! Get started today."
        image:
          type: string
          format: uri
          nullable: true
          description: URL to notification image/media
          example: "https://api.korrero.com/uploads/banner.jpg"
        action:
          type: object
          description: Action configuration for user interaction
          required:
            - type
            - data
          properties:
            type:
              type: string
              enum: [NO_ACTION, LINK, CLOSE]
              description: Type of action when user interacts
            data:
              type: object
              nullable: true
              description: Action data (URL object for LINK, null for others)
              properties:
                url:
                  type: string
                  format: uri
                target:
                  type: string
                  enum: [_blank, _self]
          example:
            type: "LINK"
            data:
              url: "https://example.com/welcome"
              target: "_blank"
        preset:
          type: string
          description: Display preset name for styling (defaults to "default")
          example: "default"
        startDate:
          type: string
          format: date-time
          nullable: true
          description: When notification becomes active (ISO 8601)
          example: "2024-01-01T00:00:00.000Z"
        endDate:
          type: string
          format: date-time
          nullable: true
          description: When notification expires (ISO 8601, null = no expiry)
          example: "2024-12-31T23:59:59.000Z"

    Error:
      type: object
      description: Standard error response
      required:
        - error
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Error code for programmatic handling
        details:
          type: object
          description: Additional error details
          additionalProperties: true

  responses:
    BadRequest:
      description: Bad request - invalid parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalidApiKey:
              summary: Invalid API key format
              value:
                error: "Invalid API key format"
                code: "INVALID_API_KEY"
            missingParameter:
              summary: Missing required parameter
              value:
                error: "Missing required parameter: type"
                code: "MISSING_PARAMETER"

    Unauthorized:
      description: Unauthorized - missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingApiKey:
              summary: Missing API key
              value:
                error: "API key is required"
            invalidApiKey:
              summary: Invalid API key
              value:
                error: "Invalid API key"

    Forbidden:
      description: Forbidden - insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "Access denied for this resource"
            code: "FORBIDDEN"

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            notificationNotFound:
              summary: Notification not found
              value:
                error: "Notification not found"
                code: "NOTIFICATION_NOT_FOUND"

    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "Too many requests from this IP, please try again later."
            code: "RATE_LIMIT_EXCEEDED"

    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "Internal server error"
            code: "INTERNAL_ERROR"


tags:
  - name: Notifications
    description: Operations for fetching notifications
  - name: Tracking
    description: Operations for tracking user interactions with notifications