# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Pirsch Tracking API
  version: 1.0.0
extends: openapi/pirsch-tracking-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 6
- target: $.paths['/hit'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a single page view server-side
      effect: write
      questions:
      - How do I track page views from my backend instead of a JavaScript snippet?
      - Which visitor details, like IP and user agent, must I forward with a page view?
      instructions:
      - text: Record a page view for {url} from IP {ip} with user agent {user_agent}.
        slots:
          url: requestBody.url
          ip: requestBody.ip
          user_agent: requestBody.user_agent
      - text: Track a visit to {url} titled {title} referred by {referrer} for IP {ip} and agent {user_agent}.
        slots:
          url: requestBody.url
          title: requestBody.title
          referrer: requestBody.referrer
          ip: requestBody.ip
          user_agent: requestBody.user_agent
      method: generated
      generated: '2026-10-01'
- target: $.paths['/hit/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Record many page views in one request
      effect: write
      questions:
      - Can I send a backlog of page views in one request?
      - What's the most efficient way to import many page hits at once?
      instructions:
      - text: Send this batch of page views in one request.
      - text: Upload the queued page hits together as a batch.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/event'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a custom event
      effect: write
      questions:
      - How do I track a button click or signup as a custom event?
      - Can I attach metadata and a duration to an event?
      instructions:
      - text: Send event {event_name} on {url} for IP {ip} and user agent {user_agent}.
        slots:
          event_name: requestBody.event_name
          url: requestBody.url
          ip: requestBody.ip
          user_agent: requestBody.user_agent
      - text: Track event {event_name} at {url} with metadata {event_meta} for IP {ip} and agent {user_agent}.
        slots:
          event_name: requestBody.event_name
          url: requestBody.url
          event_meta: requestBody.event_meta
          ip: requestBody.ip
          user_agent: requestBody.user_agent
      method: generated
      generated: '2026-10-01'
- target: $.paths['/event/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Record many custom events at once
      effect: write
      questions:
      - Can I send multiple custom events in a single call?
      - Is there a bulk endpoint for queued event tracking?
      instructions:
      - text: Send this batch of custom events.
      - text: Upload the queued events together in one request.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/session'].post
  update:
    x-apievangelist-phrasing:
      intent: Extend a visitor's session
      effect: write
      questions:
      - How do I keep a visitor's session from timing out while they stay on a page?
      - Can I extend a session without recording a new page view?
      instructions:
      - text: Keep the session alive for IP {ip} with user agent {user_agent}.
        slots:
          ip: requestBody.ip
          user_agent: requestBody.user_agent
      - text: Extend the current visitor session for {ip} using agent {user_agent}.
        slots:
          ip: requestBody.ip
          user_agent: requestBody.user_agent
      method: generated
      generated: '2026-10-01'
- target: $.paths['/session/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Extend many visitor sessions at once
      effect: write
      questions:
      - Can I extend several visitor sessions in one request?
      - Is there a batch way to send session keep-alive pings?
      instructions:
      - text: Keep this batch of visitor sessions alive.
      - text: Send all pending session keep-alive pings together.
      method: generated
      generated: '2026-10-01'