naftiko: 1.0.0-alpha2
info:
  label: Swetrix Web Analytics
  description: Unified web analytics capability combining Swetrix Events, Statistics, and Admin APIs. Enables product teams
    and developers to track user behavior, analyze traffic patterns, manage analytics projects, and monitor errors in a privacy-first,
    cookieless analytics environment.
  tags:
  - Analytics
  - Custom Events
  - Error Tracking
  - GDPR Compliant
  - Open Source
  - Privacy
  - Project Management
  - Swetrix
  - Traffic
  - Web Analytics
  created: '2026-05-03'
  modified: '2026-05-06'
binds:
- namespace: env
  keys:
    SWETRIX_API_KEY: SWETRIX_API_KEY
capability:
  consumes:
  - type: http
    namespace: swetrix-events
    baseUri: https://api.swetrix.com
    description: Records analytics events for Swetrix projects
    resources:
    - name: pageviews
      path: /log
      description: Pageview event recording
      operations:
      - name: record-pageview
        method: POST
        description: Record Pageview Event
        inputParameters:
        - name: pid
          in: body
          type: string
          required: true
          description: Project ID
        - name: pg
          in: body
          type: string
          required: false
          description: Page path
        - name: lc
          in: body
          type: string
          required: false
          description: User locale
        - name: ref
          in: body
          type: string
          required: false
          description: Referrer URL
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: custom-events
      path: /log/custom
      description: Custom event recording
      operations:
      - name: record-custom-event
        method: POST
        description: Record Custom Event
        inputParameters:
        - name: pid
          in: body
          type: string
          required: true
          description: Project ID
        - name: ev
          in: body
          type: string
          required: true
          description: Event identifier
        - name: pg
          in: body
          type: string
          required: false
          description: Page path
        - name: meta
          in: body
          type: object
          required: false
          description: Custom metadata key-value pairs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: heartbeat
      path: /log/hb
      description: Session heartbeat events
      operations:
      - name: record-heartbeat
        method: POST
        description: Record Heartbeat Event
        inputParameters:
        - name: pid
          in: body
          type: string
          required: true
          description: Project ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: errors
      path: /log/error
      description: JavaScript error recording
      operations:
      - name: record-error
        method: POST
        description: Record Error Event
        inputParameters:
        - name: pid
          in: body
          type: string
          required: true
          description: Project ID
        - name: name
          in: body
          type: string
          required: true
          description: Error name
        - name: message
          in: body
          type: string
          required: false
          description: Error message
        - name: stackTrace
          in: body
          type: string
          required: false
          description: Stack trace
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: revenue
      path: /log/revenue
      description: Revenue transaction recording
      operations:
      - name: record-revenue
        method: POST
        description: Record Revenue Transaction
        inputParameters:
        - name: pid
          in: body
          type: string
          required: true
          description: Project ID
        - name: type
          in: body
          type: string
          required: true
          description: 'Transaction type: sale, refund, subscription'
        - name: amount
          in: body
          type: number
          required: true
          description: Transaction amount
        - name: currency
          in: body
          type: string
          required: true
          description: ISO 4217 currency code
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: swetrix-statistics
    baseUri: https://api.swetrix.com
    description: Queries Swetrix analytics statistics
    authentication:
      type: apikey
      key: X-Api-Key
      value: '{{SWETRIX_API_KEY}}'
      placement: header
    resources:
    - name: traffic-log
      path: /v1/log
      description: Aggregated traffic log data
      operations:
      - name: get-traffic-log
        method: GET
        description: Get Traffic Log
        inputParameters:
        - name: pid
          in: query
          type: string
          required: true
          description: Project ID
        - name: timeBucket
          in: query
          type: string
          required: true
          description: 'Time bucket: minute, hour, day, week, month, year'
        - name: period
          in: query
          type: string
          required: true
          description: 'Period: 1h, today, 7d, 4w, 3M, 12M, all'
        - name: from
          in: query
          type: string
          required: false
          description: Custom range start date YYYY-MM-DD
        - name: to
          in: query
          type: string
          required: false
          description: Custom range end date YYYY-MM-DD
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: performance
      path: /v1/log/performance
      description: Frontend performance metrics
      operations:
      - name: get-performance-metrics
        method: GET
        description: Get Performance Metrics
        inputParameters:
        - name: pid
          in: query
          type: string
          required: true
          description: Project ID
        - name: timeBucket
          in: query
          type: string
          required: true
          description: Time bucket
        - name: period
          in: query
          type: string
          required: true
          description: Period
        - name: measure
          in: query
          type: string
          required: false
          description: 'Aggregation: median, average, p95, quantiles'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: birdseye
      path: /v1/log/birdseye
      description: Traffic summary across projects
      operations:
      - name: get-birdseye-summary
        method: GET
        description: Get Birdseye Traffic Summary
        inputParameters:
        - name: pids
          in: query
          type: string
          required: false
          description: Comma-separated project IDs
        - name: period
          in: query
          type: string
          required: true
          description: Time period
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: live-visitors
      path: /v1/log/live-visitors
      description: Currently active visitors
      operations:
      - name: get-live-visitors
        method: GET
        description: Get Live Visitors
        inputParameters:
        - name: pid
          in: query
          type: string
          required: true
          description: Project ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: sessions
      path: /v1/log/sessions
      description: Individual visitor sessions
      operations:
      - name: list-sessions
        method: GET
        description: List Sessions
        inputParameters:
        - name: pid
          in: query
          type: string
          required: true
          description: Project ID
        - name: period
          in: query
          type: string
          required: true
          description: Time period
        - name: take
          in: query
          type: integer
          required: false
          description: Results per page (max 150)
        - name: skip
          in: query
          type: integer
          required: false
          description: Pagination offset
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: funnels
      path: /v1/log/funnel
      description: Conversion funnel analysis
      operations:
      - name: get-funnel-analysis
        method: GET
        description: Get Funnel Analysis
        inputParameters:
        - name: pid
          in: query
          type: string
          required: true
          description: Project ID
        - name: period
          in: query
          type: string
          required: true
          description: Time period
        - name: pages
          in: query
          type: string
          required: false
          description: JSON array of page paths
        - name: funnelId
          in: query
          type: string
          required: false
          description: Saved funnel ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: errors-list
      path: /v1/log/errors
      description: Error event groups
      operations:
      - name: list-errors
        method: GET
        description: List Error Events
        inputParameters:
        - name: pid
          in: query
          type: string
          required: true
          description: Project ID
        - name: period
          in: query
          type: string
          required: true
          description: Time period
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: custom-events-data
      path: /v1/log/custom-events
      description: Custom event analytics
      operations:
      - name: get-custom-events
        method: GET
        description: Get Custom Events Data
        inputParameters:
        - name: pid
          in: query
          type: string
          required: true
          description: Project ID
        - name: timeBucket
          in: query
          type: string
          required: true
          description: Time bucket
        - name: period
          in: query
          type: string
          required: true
          description: Time period
        - name: customEvents
          in: query
          type: string
          required: true
          description: JSON array of event names
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: swetrix-admin
    baseUri: https://api.swetrix.com
    description: Manages Swetrix analytics projects and resources
    authentication:
      type: apikey
      key: X-Api-Key
      value: '{{SWETRIX_API_KEY}}'
      placement: header
    resources:
    - name: projects
      path: /v1/project
      description: Analytics project management
      operations:
      - name: list-projects
        method: GET
        description: List Projects
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-project
        method: POST
        description: Create Project
        inputParameters:
        - name: name
          in: body
          type: string
          required: true
          description: Project display name (max 50 chars)
        - name: isCaptcha
          in: body
          type: boolean
          required: false
          description: Enable CAPTCHA tracking
        - name: isPasswordProtected
          in: body
          type: boolean
          required: false
          description: Require dashboard password
        - name: organisationId
          in: body
          type: string
          required: false
          description: Organisation to assign project to
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: project-detail
      path: /v1/project/{id}
      description: Single project operations
      operations:
      - name: get-project
        method: GET
        description: Get Project
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
          description: Project ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: update-project
        method: PUT
        description: Update Project
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
          description: Project ID
        - name: name
          in: body
          type: string
          required: false
          description: New project name
        - name: active
          in: body
          type: boolean
          required: false
          description: Enable/disable tracking
        - name: public
          in: body
          type: boolean
          required: false
          description: Public dashboard visibility
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: delete-project
        method: DELETE
        description: Delete Project
        inputParameters:
        - name: id
          in: path
          type: string
          required: true
          description: Project ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: organisations
      path: /v1/organisation
      description: Organisation management
      operations:
      - name: list-organisations
        method: GET
        description: List Organisations
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-organisation
        method: POST
        description: Create Organisation
        inputParameters:
        - name: name
          in: body
          type: string
          required: true
          description: Organisation name (max 50 chars)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: swetrix-analytics-api
    description: Unified REST API for Swetrix web analytics management and querying.
    resources:
    - path: /v1/events/pageviews
      name: pageviews
      description: Record pageview events
      operations:
      - method: POST
        name: record-pageview
        description: Record Pageview Event
        call: swetrix-events.record-pageview
        with:
          pid: rest.pid
          pg: rest.pg
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/events/custom
      name: custom-events
      description: Record custom events
      operations:
      - method: POST
        name: record-custom-event
        description: Record Custom Event
        call: swetrix-events.record-custom-event
        with:
          pid: rest.pid
          ev: rest.ev
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/events/errors
      name: error-events
      description: Record JavaScript error events
      operations:
      - method: POST
        name: record-error
        description: Record Error Event
        call: swetrix-events.record-error
        with:
          pid: rest.pid
          name: rest.name
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/analytics/traffic
      name: traffic
      description: Query traffic analytics
      operations:
      - method: GET
        name: get-traffic-log
        description: Get Traffic Log
        call: swetrix-statistics.get-traffic-log
        with:
          pid: rest.pid
          timeBucket: rest.timeBucket
          period: rest.period
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/analytics/performance
      name: performance
      description: Query performance metrics
      operations:
      - method: GET
        name: get-performance-metrics
        description: Get Performance Metrics
        call: swetrix-statistics.get-performance-metrics
        with:
          pid: rest.pid
          timeBucket: rest.timeBucket
          period: rest.period
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/analytics/live-visitors
      name: live-visitors
      description: Get currently active visitors
      operations:
      - method: GET
        name: get-live-visitors
        description: Get Live Visitors
        call: swetrix-statistics.get-live-visitors
        with:
          pid: rest.pid
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/analytics/sessions
      name: sessions
      description: List visitor sessions
      operations:
      - method: GET
        name: list-sessions
        description: List Sessions
        call: swetrix-statistics.list-sessions
        with:
          pid: rest.pid
          period: rest.period
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/analytics/funnels
      name: funnels
      description: Analyze conversion funnels
      operations:
      - method: GET
        name: get-funnel-analysis
        description: Get Funnel Analysis
        call: swetrix-statistics.get-funnel-analysis
        with:
          pid: rest.pid
          period: rest.period
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/analytics/errors
      name: errors
      description: Query error statistics
      operations:
      - method: GET
        name: list-errors
        description: List Error Events
        call: swetrix-statistics.list-errors
        with:
          pid: rest.pid
          period: rest.period
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/projects
      name: projects
      description: Manage analytics projects
      operations:
      - method: GET
        name: list-projects
        description: List Projects
        call: swetrix-admin.list-projects
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: create-project
        description: Create Project
        call: swetrix-admin.create-project
        with:
          name: rest.name
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/projects/{id}
      name: project-detail
      description: Single project operations
      operations:
      - method: GET
        name: get-project
        description: Get Project
        call: swetrix-admin.get-project
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: delete-project
        description: Delete Project
        call: swetrix-admin.delete-project
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: swetrix-analytics-mcp
    transport: http
    description: MCP server for AI-assisted web analytics with Swetrix.
    tools:
    - name: record-pageview
      description: Record a pageview event to Swetrix analytics
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: swetrix-events.record-pageview
      with:
        pid: tools.pid
        pg: tools.pg
      outputParameters:
      - type: object
        mapping: $.
    - name: record-custom-event
      description: Record a custom analytics event with optional metadata
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: swetrix-events.record-custom-event
      with:
        pid: tools.pid
        ev: tools.ev
      outputParameters:
      - type: object
        mapping: $.
    - name: record-error
      description: Record a JavaScript error event for dashboard aggregation
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: swetrix-events.record-error
      with:
        pid: tools.pid
        name: tools.name
      outputParameters:
      - type: object
        mapping: $.
    - name: record-revenue
      description: Record a revenue transaction (sale, refund, subscription)
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: swetrix-events.record-revenue
      with:
        pid: tools.pid
        type: tools.type
        amount: tools.amount
        currency: tools.currency
      outputParameters:
      - type: object
        mapping: $.
    - name: get-traffic-log
      description: Query aggregated traffic data for a project by time bucket and period
      hints:
        readOnly: true
        idempotent: true
      call: swetrix-statistics.get-traffic-log
      with:
        pid: tools.pid
        timeBucket: tools.timeBucket
        period: tools.period
      outputParameters:
      - type: object
        mapping: $.
    - name: get-performance-metrics
      description: Query frontend performance metrics including DNS, TLS, TTFB, and page load times
      hints:
        readOnly: true
        idempotent: true
      call: swetrix-statistics.get-performance-metrics
      with:
        pid: tools.pid
        timeBucket: tools.timeBucket
        period: tools.period
      outputParameters:
      - type: object
        mapping: $.
    - name: get-live-visitors
      description: Get currently active visitors with device, browser, OS, and country details
      hints:
        readOnly: true
        idempotent: true
      call: swetrix-statistics.get-live-visitors
      with:
        pid: tools.pid
      outputParameters:
      - type: object
        mapping: $.
    - name: list-sessions
      description: List individual visitor sessions with device and page details
      hints:
        readOnly: true
        idempotent: true
      call: swetrix-statistics.list-sessions
      with:
        pid: tools.pid
        period: tools.period
      outputParameters:
      - type: object
        mapping: $.
    - name: get-funnel-analysis
      description: Analyze conversion rates across a sequence of pages in a funnel
      hints:
        readOnly: true
        idempotent: true
      call: swetrix-statistics.get-funnel-analysis
      with:
        pid: tools.pid
        period: tools.period
      outputParameters:
      - type: object
        mapping: $.
    - name: list-errors
      description: List JavaScript error groups with occurrence counts and affected sessions
      hints:
        readOnly: true
        idempotent: true
      call: swetrix-statistics.list-errors
      with:
        pid: tools.pid
        period: tools.period
      outputParameters:
      - type: object
        mapping: $.
    - name: get-custom-events
      description: Query custom event analytics grouped by time for named events
      hints:
        readOnly: true
        idempotent: true
      call: swetrix-statistics.get-custom-events
      with:
        pid: tools.pid
        timeBucket: tools.timeBucket
        period: tools.period
        customEvents: tools.customEvents
      outputParameters:
      - type: object
        mapping: $.
    - name: list-projects
      description: List all Swetrix analytics projects for the account
      hints:
        readOnly: true
        idempotent: true
      call: swetrix-admin.list-projects
      outputParameters:
      - type: object
        mapping: $.
    - name: create-project
      description: Create a new Swetrix analytics project
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: swetrix-admin.create-project
      with:
        name: tools.name
      outputParameters:
      - type: object
        mapping: $.
    - name: get-project
      description: Get configuration and settings for a specific project
      hints:
        readOnly: true
        idempotent: true
      call: swetrix-admin.get-project
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: delete-project
      description: Permanently delete a project and all associated analytics data
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: swetrix-admin.delete-project
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.