openapi.yaml

openapi: 3.1.0

info:
  title: LiveSession API
  version: v1

servers:
  - url: https://api.livesession.io/v1
    description: Production server (uses live data)

paths:
  # BEGIN Sessions
  /sessions:
    x-fern-sdk-group-name: sessions
    x-fern-sdk-method-name: list
    get:
      summary: Get Sessions
      security:
        - livesession_oauth: [ users.sessions:read ]
        - api_token: [ users.sessions:read ]
      description: |
        ---
        title: List sessions
        group: [ENDPOINTS]
        ---
        
        List of all sessions
      tags:
        - Sessions
      parameters:
        - name: page
          in: query
          description: The number of page to start with (default 0, max 10000).
          schema:
            type: integer
        - name: size
          in: query
          description: The number of page's size (default 25, max 100).
          schema:
            type: integer
        - name: email
          in: query
          description: The email address that you have associated with a session via [identify](/docs/api/browser/methods#identify).
          schema:
            type: string
        - name: visitor_id
          in: query
          description: The visitor ID.
          schema:
            type: string
        - name: tz
          in: query
          description: IANA timezone. Default Europe/London if RelativeDateString is applied.
          schema:
            type: string
        - name: date_from
          in: query
          description: |
            [ISO 8601](https://wikipedia.org/wiki/ISO_8601) string or [RelativeDateString](/docs/api/rest/RelativeDateString).
          schema:
            oneOf:
              - type: string
              - $ref: '#/components/schemas/RelativeDateString'
        - name: date_to
          in: query
          description: |
            [ISO 8601](https://wikipedia.org/wiki/ISO_8601) string or [RelativeDateString](/docs/api/rest/RelativeDateString).
          schema:
            oneOf:
              - type: string
              - $ref: '#/components/schemas/RelativeDateString'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetListSessionsResponse'
        '400':
          description: 400 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'


  # BEGIN Alerts
  /alerts:
    get:
      x-fern-sdk-group-name: alerts
      x-fern-sdk-method-name: list
      summary: Get all alerts
      security:
        - livesession_oauth: [ alerts:read ]
      description: |
        ---
        title: List alerts
        group: [ENDPOINTS]
        ---
        
        List of all alerts
      tags:
        - Alerts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Alert'
        '400':
          description: 400 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      x-fern-sdk-group-name: alerts
      x-fern-sdk-method-name: create
      summary: Create an alert
      security:
        - livesession_oauth: [ alerts:write ]
      description: |
        ---
        title: Create alert
        group: [ENDPOINTS]
        ---
        
        Create alert
      tags:
        - Alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertCreate'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
        '400':
          description: 400 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /alerts/{id}:
    put:
      x-fern-sdk-group-name: alerts
      x-fern-sdk-method-name: update
      summary: Update an alert by ID
      security:
        - livesession_oauth: [ alerts:write ]
      description: |
        ---
        title: Update alert
        group: [ENDPOINTS]
        ---
        
        Update alert by ID
      tags:
        - Alerts
      parameters:
        - in: path
          name: id
          required: true
          description: Unique identifier of the alert to update
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertUpdate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
        '400':
          description: 400 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      x-fern-sdk-group-name: alerts
      x-fern-sdk-method-name: delete
      summary: Delete an alert by ID
      security:
        - livesession_oauth: [ alerts:write ]
      description: |
        ---
        title: Delete alert
        group: [ENDPOINTS]
        ---
        
        Delete alert by ID
      tags:
        - Alerts
      parameters:
        - in: path
          name: id
          required: true
          description: Unique identifier of the alert to delete
          schema:
            type: string
      responses:
        '200':
          description: Alert deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  alert_id:
                    type: string
                    description: ID of the alert that was deleted
                  deleted:
                    type: boolean
                    description: Indicates whether the alert was successfully deleted
        '400':
          description: 400 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # END Alerts

  # BEGIN Webhooks
  /webhooks:
    get:
      x-fern-sdk-group-name: webhooks
      x-fern-sdk-method-name: list
      summary: Get a list of webhooks
      security:
        - livesession_oauth: [ webhooks:read ]
      description: |
        ---
        title: List webhooks
        group: [ENDPOINTS]
        ---
        
        List of all webhooks
      tags:
        - Webhooks
      responses:
        '200':
          description: List of webhooks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
        '400':
          description: 400 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      x-fern-sdk-group-name: webhooks
      x-fern-sdk-method-name: create
      summary: Create a webhook
      security:
        - livesession_oauth: [ webhooks:write ]
      description: |
        ---
        title: Create webhook
        group: [ENDPOINTS]
        ---
        
        Create a webhook
      tags:
        - Webhooks
      requestBody:
        description: Webhook creation request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
      responses:
        '200':
          description: Webhook created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: 400 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /webhooks/{id}:
    put:
      x-fern-sdk-group-name: webhooks
      x-fern-sdk-method-name: update
      summary: Update a webhook
      security:
        - livesession_oauth: [ webhooks:write ]
      description: |
        ---
        title: Update webhook
        group: [ENDPOINTS]
        ---
        
        Update a webhook
      tags:
        - Webhooks
      parameters:
        - name: id
          in: path
          description: ID of the webhook to update
          required: true
          schema:
            type: string
        - name: version
          in: query
          description: API version
          required: true
          schema:
            type: string
            enum: [ v1.0 ]
      requestBody:
        description: Webhook update request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUpdate'
      responses:
        '200':
          description: Webhook updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: 400 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 404 response
        '500':
          description: 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

    delete:
      x-fern-sdk-group-name: webhooks
      x-fern-sdk-method-name: delete
      summary: Delete a webhook
      security:
        - livesession_oauth: [ webhooks:write ]
      description: |
        ---
        title: Delete webhook
        group: [ENDPOINTS]
        ---
        
        Delete a webhook
      tags:
        - Webhooks
      parameters:
        - name: id
          in: path
          description: ID of the webhook to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookDeleted'
        '400':
          description: 400 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 404 response
        '500':
          description: 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  # END Webhooks

  # BEGIN Websites
  /websites:
    get:
      x-fern-sdk-group-name: websites
      x-fern-sdk-method-name: list
      summary: Get a list of websites
      security:
        - livesession_oauth: [ websites:read ]
      description: |
        ---
        title: List websites
        group: [ENDPOINTS]
        ---
        
        List of all websites
      tags:
        - Websites
      responses:
        '200':
          description: List of websites
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Website'
        '400':
          description: 400 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      x-fern-sdk-group-name: websites
      x-fern-sdk-method-name: create
      summary: Create a website
      security:
        - livesession_oauth: [ websites:write ]
      description: |
        ---
        title: Create website
        group: [ENDPOINTS]
        ---
        
        Create a website
      tags:
        - Websites
      requestBody:
        description: Website creation request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebsiteCreate'
      responses:
        '200':
          description: Create a website
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Website'
        '400':
          description: 400 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  # END Websites

components:
  securitySchemes:
    api_token:
      type: apiKey
      name: Authorization
      description: "[API Tokens](https://developers.livesession.io/rest-api/introduction/#creating-a-personal-access-token)"
      in: header

    livesession_oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://apis.livesession.io/accounts/v1/oauth2/authorize
          tokenUrl: https://apis.livesession.io/accounts/v1/oauth2/access_token
          refreshUrl: https://apis.livesession.io/accounts/v1/oauth2/access_token
          scopes:
            users.sessions:read: read user sessions

            webhooks:read: read webhooks
            webhooks:write: write webhooks

            alerts:read: read alerts
            alerts:write: write alerts

            websites:read: read websites
            websites:write: write websites

            payment_intents:write: write payment intents
            payment_intents.confirm: confirm payment intents

  schemas:

    # BEGIN Errors
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: Type of error (e.g., validation_error, authentication_error)
            code:
              type: string
              description: Machine-readable error code
            param:
              type: string
              description: Name of the parameter that caused the error
            message:
              type: string
              description: Human-readable error message
            http_status_code:
              type: integer
              description: HTTP status code associated with the error
            request_id:
              type: string
              description: Unique identifier for the request that caused the error

    # END Errors

    # BEGIN Sessions
    Session:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the session
        website_id:
          type: string
          description: ID of the website where the session was recorded
        session_url:
          type: string
          description: URL to view the session in LiveSession dashboard
        creation_timestamp:
          type: integer
          description: Unix timestamp when the session was created
        duration:
          type: integer
          description: Total duration of the session in seconds
        end_timestamp:
          type: integer
          description: Unix timestamp when the session ended
        active_time:
          type: integer
          description: Total time the user was actively interacting with the page in seconds
        end_url:
          type: string
          description: The last URL visited during the session
        expiration_timestamp:
          type: integer
          description: Unix timestamp when the session recording will expire
        last_event_timestamp:
          type: integer
          description: Unix timestamp of the last event recorded in the session
        product:
          type: string
          description: Product identifier associated with the session
        device:
          type: string
          description: Device type (e.g., desktop, mobile, tablet)
        tags:
          type: array
          description: Custom tags associated with the session
          items:
            type: string
        last_seen_page_view_id:
          type: string
          description: ID of the last page view in the session
        seen:
          type: boolean
          description: Whether the session has been viewed in the dashboard
        referrer:
          type: string
          description: URL where the user came from before starting the session
        start_url:
          type: string
          description: First URL visited during the session
        visitor_first_session:
          type: boolean
          description: Whether this is the visitor's first session
        engagment_score:
          type: number
          description: Calculated engagement score for the session (0-100)
        visitor:
          $ref: '#/components/schemas/SessionVisitorData'
        resolution:
          $ref: '#/components/schemas/SessionResolutionData'
        os:
          $ref: '#/components/schemas/SessionOsData'
        browser:
          $ref: '#/components/schemas/SessionBrowserData'
        utm:
          $ref: '#/components/schemas/SessionUTMData'
        page_views_statistics:
          $ref: '#/components/schemas/SessionPageViewsStatisticsData'
        events_statistics:
          $ref: '#/components/schemas/SessionEventsStatisticsData'

    SessionVisitorData:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the visitor
        ip:
          type: string
          description: IP address of the visitor
        geolocation:
          $ref: '#/components/schemas/SessionVisitorDataGeolocation'
        name:
          type: string
          description: Name of the visitor if identified
        email:
          type: string
          description: Email address of the visitor if identified
        email_hash:
          type: string
          description: Hashed version of the visitor's email for privacy
        params:
          type: array
          description: Custom parameters associated with the visitor
          items:
            $ref: '#/components/schemas/SessionVisitorDataParams'
        last_session_timestamp:
          type: integer
          description: Unix timestamp of the visitor's last session
        first_session_timestamp:
          type: integer
          description: Unix timestamp of the visitor's first session

    SessionOsData:
      type: object
      properties:
        name:
          type: string
          description: Operating system name (e.g., Windows, macOS, iOS)
        version:
          type: string
          description: Operating system version

    SessionBrowserData:
      type: object
      properties:
        description:
          type: string
          description: Full browser description string
        name:
          type: string
          description: Browser name (e.g., Chrome, Firefox, Safari)
        version:
          type: string
          description: Browser version

    SessionUTMData:
      type: object
      properties:
        source:
          type: string
          description: UTM source parameter (e.g., google, facebook)
        medium:
          type: string
          description: UTM medium parameter (e.g., cpc, social)
        campaign:
          type: string
          description: UTM campaign parameter
        term:
          type: string
          description: UTM term parameter (search keywords)
        content:
          type: string
          description: UTM content parameter

    SessionEventsStatisticsData:
      type: object
      properties:
        clicks:
          type: integer
          description: Total number of clicks during the session
        error_clicks:
          type: integer
          description: Number of clicks on error elements
        rage_clicks:
          type: integer
          description: Number of rapid clicks indicating user frustration
        error_logs:
          type: integer
          description: Number of JavaScript errors logged
        net_errors:
          type: integer
          description: Number of network errors encountered

    SessionPageViewLocationData:
      type: object
      properties:
        base:
          type: string
          description: Base URL of the page
        href:
          type: string
          description: Full URL of the page
        origin:
          type: string
          description: Origin of the page (protocol + hostname)
        referrer:
          type: string
          description: URL of the previous page

    SessionPageViewViewPortData:
      type: object
      properties:
        height:
          type: integer
          description: Viewport height in pixels
        width:
          type: integer
          description: Viewport width in pixels

    SessionVisitorDataGeolocation:
      type: object
      properties:
        country_code:
          type: string
          description: Two-letter country code (ISO 3166-1 alpha-2)
        city:
          type: string
          description: City name
        region:
          type: string
          description: Region or state name

    SessionVisitorDataParams:
      type: object
      properties:
        name:
          type: string
          description: Parameter name
        value:
          type: string
          description: Parameter value

    SessionResolutionData:
      type: object
      properties:
        height:
          type: integer
          description: Screen height in pixels
        width:
          type: integer
          description: Screen width in pixels
        resolution:
          type: string
          description: Screen resolution (e.g., "1920x1080")

    SessionPageViewsStatisticsData:
      type: object
      properties:
        count:
          type: integer
          description: Total number of page views in the session

    GetListSessionsResponse:
      type: object
      properties:
        total:
          type: integer
          description: Total number of sessions matching the query
        page:
          $ref: '#/components/schemas/Pagination'
        sessions:
          type: array
          description: List of session objects
          items:
            $ref: '#/components/schemas/Session'

    Pagination:
      type: object
      properties:
        num:
          type: integer
          description: Current page number
        size:
          type: integer
          description: Number of items per page

    RelativeDateString:
      type: string
      description: |
        * `TODAY` - Today since midnight
        * `YESTERDAY` - Yesterday since midnight
        * `BEGINNING_OF_WEEK` - Nearest monday since midnight
        * `BEGINNING_OF_MONTH` - 1st of the month since midnight
        * `BEGINNING_OF_PREV_MONTH` - Previous 1st of the month since midnight
        * `TODAY-7DAYS` - Exact 7 days ago since midnight
        * `TODAY-30DAYS` - Exact 30 days ago since midnight
      enum:
        - TODAY
        - YESTERDAY
        - BEGINNING_OF_WEEK
        - BEGINNING_OF_MONTH
        - BEGINNING_OF_PREV_MONTH
        - TODAY-7DAYS
        - TODAY-30DAYS
    # END Sessions

    # BEGIN Alerts
    AlertCreate:
      type: object
      required:
        - name
        - events
        - provider
      properties:
        name:
          type: string
          description: Name of the alert for easy identification
        events:
          type: array
          description: List of events that will trigger the alert
          items:
            $ref: '#/components/schemas/AlertEvent'
        provider:
          $ref: '#/components/schemas/AlertProviderEnum'
          description: Notification provider for the alert, `slack` or `webhooks`
        slack_channel_id:
          type: string
          description: Slack channel ID where notifications will be sent (required if provider is `slack`)
        webhook_id:
          type: string
          description: Webhook ID where notifications will be sent (required if provider is `webhooks`)

    AlertUpdate:
      type: object
      properties:
        name:
          type: string
          description: New name for the alert
        events:
          type: array
          description: Updated list of events that will trigger the alert
          items:
            $ref: '#/components/schemas/AlertEvent'
        provider:
          $ref: '#/components/schemas/AlertProviderEnum'
          description: Updated notification provider for the alert
        slack_channel_id:
          type: string
          description: Updated Slack channel ID for notifications
        webhook_id:
          type: string
          description: Updated webhook ID for notifications

    AlertEvent:
      type: object
      properties:
        kind:
          type: integer
          description: Kind of event, more info [here](/docs/api/rest/EventKind)
        value:
          type: string
          description: Value or threshold that triggers the alert

    Alert:
      type: object
      properties:
        alert_id:
          type: string
          description: Unique identifier for the alert
        name:
          type: string
          description: Name of the alert
        events:
          type: array
          description: List of events that trigger the alert
          items:
            $ref: '#/components/schemas/AlertEvent'
        provider:
          $ref: '#/components/schemas/AlertProviderEnum'
          description: Notification provider for the alert
        slack_channel_id:
          type: string
          description: Slack channel ID for notifications
        webhook_id:
          type: string
          description: Webhook ID for notifications
        enabled:
          type: boolean
          description: Whether the alert is currently active
        creation_date:
          type: string
          description: |
            [ISO 8601](https://wikipedia.org/wiki/ISO_8601) timestamp when the alert was created

    AlertDeleted:
      type: object
      properties:
        alert_id:
          type: string
          description: ID of the deleted alert
        deleted:
          type: boolean
          description: Confirmation that the alert was deleted

    AlertProviderEnum:
      type: string
      description: Available notification providers for alerts
      enum:
        - slack
        - webhooks
    # END Alerts

    # BEGIN Webhooks
    WebhookCreate:
      type: object
      required:
        - url
        - website_id
        - version
      properties:
        url:
          type: string
          description: URL for the webhook
        website_id:
          type: string
          description: Website ID
        version:
          type: string
          description: API version (e.g., v1.0)
    WebhookUpdate:
      type: object
      required:
        - url
        - website_id
        - version
      properties:
        url:
          type: string
          description: URL for the webhook
        website_id:
          type: string
          description: Website ID
        version:
          type: string
          description: API version (e.g., v1.0)
    Webhook:
      type: object
      properties:
        webhook_id:
          type: string
          description: Webhook ID
        url:
          type: string
          description: URL for the webhook
        website:
          type: string
          description: Website name
        website_id:
          type: string
          description: Website ID
        version:
          type: string
          description: API version
        enabled:
          type: boolean
          description: Webhook enabled status
        created_date:
          type: integer
          format: int64
          description: Unix timestamp for creation date
        created_by:
          type: string
          description: Creator of the webhook
    WebhookDeleted:
      type: object
      properties:
        webhook_id:
          type: string
          description: Webhook ID
        deleted:
          type: boolean
          description: Indicates if the webhook was deleted
    # END Webhooks

    # BEGIN Websites
    Website:
      type: object
      properties:
        website_id:
          type: string
          description: Unique identifier for the website
        host:
          type: string
          description: Domain name or hostname of the website (e.g., example.com)

    WebsiteCreate:
      type: object
      required:
        - host
      properties:
        host:
          type: string
          description: Domain name or hostname of the website to track
        description:
          type: string
          description: Optional description of the website for organization purposes
    # END Websites