openapi: 3.0.3
info:
  title: Boltic Streams API
  description: >-
    The Boltic Streams API provides real-time event streaming capabilities for
    tracking custom events and streaming data from websites, mobile apps, and
    servers. It includes source debugger tools for confirming API call delivery,
    an event analysis dashboard for monitoring event flows, and real-time data
    processing for actionable insights. Streams centralize, process, and enable
    analysis of streaming data for better decision-making and performance
    optimization.
  version: 1.0.0
  contact:
    name: Boltic
    url: https://www.boltic.io
  license:
    name: Proprietary
    url: https://www.boltic.io/terms
servers:
  - url: https://api.boltic.io/v1
    description: Boltic Streams API
security:
  - bearerAuth: []
tags:
  - name: Destinations
    description: Manage stream destinations for event delivery
  - name: Events
    description: Send and query events
  - name: Stream Sources
    description: Manage stream sources for event ingestion
paths:
  /streams/sources:
    get:
      operationId: listStreamSources
      summary: Boltic List all stream sources
      description: Retrieve a list of all configured stream sources.
      tags:
        - Stream Sources
      responses:
        '200':
          description: A list of stream sources
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/StreamSource'
    post:
      operationId: createStreamSource
      summary: Boltic Create a new stream source
      description: Create a new source for ingesting events into the stream.
      tags:
        - Stream Sources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StreamSourceInput'
      responses:
        '201':
          description: Stream source created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamSource'
  /streams/sources/{sourceId}:
    get:
      operationId: getStreamSource
      summary: Boltic Get a stream source by ID
      tags:
        - Stream Sources
      parameters:
        - name: sourceId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Stream source details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamSource'
    delete:
      operationId: deleteStreamSource
      summary: Boltic Delete a stream source
      tags:
        - Stream Sources
      parameters:
        - name: sourceId
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Stream source deleted
  /streams/sources/{sourceId}/debug:
    get:
      operationId: debugStreamSource
      summary: Boltic Debug a stream source
      description: >-
        Access the source debugger to confirm that API calls from your website,
        mobile app, or servers are arriving at the stream source.
      tags:
        - Stream Sources
      parameters:
        - name: sourceId
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Recent events received by this source
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  connected:
                    type: boolean
                  lastEventAt:
                    type: string
                    format: date-time
  /streams/events:
    post:
      operationId: sendEvent
      summary: Boltic Send an event
      description: Send a custom event to a stream source for processing.
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventInput'
      responses:
        '202':
          description: Event accepted for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  eventId:
                    type: string
                  status:
                    type: string
                    enum: [accepted]
    get:
      operationId: queryEvents
      summary: Boltic Query events
      description: >-
        Query and analyze events using the event analysis dashboard for
        monitoring event flows.
      tags:
        - Events
      parameters:
        - name: sourceId
          in: query
          schema:
            type: string
        - name: eventType
          in: query
          schema:
            type: string
        - name: from
          in: query
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Event query results
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  summary:
                    type: object
                    properties:
                      totalEvents:
                        type: integer
                      uniqueEventTypes:
                        type: integer
                      timeRange:
                        type: object
                        properties:
                          from:
                            type: string
                            format: date-time
                          to:
                            type: string
                            format: date-time
  /streams/destinations:
    get:
      operationId: listStreamDestinations
      summary: Boltic List stream destinations
      tags:
        - Destinations
      responses:
        '200':
          description: A list of stream destinations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/StreamDestination'
    post:
      operationId: createStreamDestination
      summary: Boltic Create a stream destination
      description: Configure a destination for delivering stream events.
      tags:
        - Destinations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StreamDestinationInput'
      responses:
        '201':
          description: Stream destination created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamDestination'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    StreamSource:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum: [javascript, server, mobile, webhook]
        writeKey:
          type: string
          description: API key for sending events to this source
        status:
          type: string
          enum: [active, inactive]
        eventsToday:
          type: integer
        createdAt:
          type: string
          format: date-time
    StreamSourceInput:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
        type:
          type: string
          enum: [javascript, server, mobile, webhook]
    Event:
      type: object
      properties:
        id:
          type: string
        sourceId:
          type: string
        type:
          type: string
          description: Event type name (e.g., page_view, purchase, signup)
        properties:
          type: object
          additionalProperties: true
          description: Custom event properties
        context:
          type: object
          properties:
            ip:
              type: string
            userAgent:
              type: string
            locale:
              type: string
            page:
              type: object
              properties:
                url:
                  type: string
                title:
                  type: string
                referrer:
                  type: string
        userId:
          type: string
        anonymousId:
          type: string
        timestamp:
          type: string
          format: date-time
        receivedAt:
          type: string
          format: date-time
    EventInput:
      type: object
      required:
        - sourceId
        - type
      properties:
        sourceId:
          type: string
        type:
          type: string
        properties:
          type: object
          additionalProperties: true
        userId:
          type: string
        anonymousId:
          type: string
        timestamp:
          type: string
          format: date-time
        context:
          type: object
          additionalProperties: true
    StreamDestination:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        config:
          type: object
          additionalProperties: true
        status:
          type: string
          enum: [active, inactive]
        createdAt:
          type: string
          format: date-time
    StreamDestinationInput:
      type: object
      required:
        - name
        - type
        - config
      properties:
        name:
          type: string
        type:
          type: string
        config:
          type: object
          additionalProperties: true
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        details:
          type: string
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'