# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Thehiveryiq Com Vault Visits API
  version: 1.0.0
extends: openapi/thehiveryiq-com-vault-visits-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 9
- target: $.paths['/v1/vault/visit'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a vault page visit beacon
      effect: write
      questions:
      - How do I log that someone opened a vault page, with dwell time and scroll depth?
      - Does every visit beacon trigger a notification or only one per session?
      instructions:
      - text: Record a visit to vault {slug} from session {visitor_session}.
        slots:
          slug: requestBody.slug
          visitor_session: requestBody.visitor_session
      - text: Log a {event} beacon on vault {slug} with {dwell_s} seconds dwell and {scroll_pct}% scroll.
        slots:
          event: requestBody.event
          slug: requestBody.slug
          dwell_s: requestBody.dwell_s
          scroll_pct: requestBody.scroll_pct
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/vault/visits/recent'].get
  update:
    x-apievangelist-phrasing:
      intent: List the most recent vault visits
      effect: read
      questions:
      - Who has opened any of my vault pages most recently?
      - Can I read the latest raw entries from the visit log?
      instructions:
      - text: Show the {limit} most recent vault visits.
        slots:
          limit: query.limit
      - text: Read the latest entries across all vault visit logs.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/vault/visits/by-slug'].get
  update:
    x-apievangelist-phrasing:
      intent: Get visit history for one vault
      effect: read
      questions:
      - Every visit to one specific vault, newest first — where do I get that?
      - Does the per-vault history separate real viewers from bots?
      instructions:
      - text: Show all visits to vault {slug}.
        slots:
          slug: query.slug
      - text: Get the last {limit} visits and bot classification for vault {slug}.
        slots:
          limit: query.limit
          slug: query.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/vault/visits/by-company'].get
  update:
    x-apievangelist-phrasing:
      intent: Summarize visits across all vaults
      effect: read
      questions:
      - What does an at-a-glance summary of every tracked vault look like, one row each?
      - Which vaults have any visits at all?
      instructions:
      - text: Summarize visit counts for every tracked vault.
      - text: Give me the per-vault dashboard rollup.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/vault/visits/health'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the vault visit tracker's health
      effect: read
      questions:
      - Is the vault visit tracking service healthy?
      - Can I confirm the visit beacon endpoint is working?
      instructions:
      - text: Check vault visit tracker health.
      - text: Confirm the visit tracking service is up.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/vault/visits/leaderboard'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank vaults by engagement
      effect: read
      questions:
      - Which vaults are getting the most engagement from unique viewers and re-opens?
      - What is the engagement score used to rank vaults?
      instructions:
      - text: Rank my vaults by engagement intensity.
      - text: Show the vault engagement leaderboard.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/vault/visits/forwards'].get
  update:
    x-apievangelist-phrasing:
      intent: Find vaults forwarded to new viewers
      effect: read
      questions:
      - Has any prospect forwarded a vault to a colleague?
      - Can I see the per-viewer breakdown for vaults opened by a second person?
      instructions:
      - text: List vaults that were forwarded to a second viewer.
      - text: Show which vaults were shared internally by prospects.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/vault/visits/register-label'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach a human label to a vault slug
      effect: write
      questions:
      - Can I name a new vault slug without redeploying?
      - Do runtime labels override labels defined in code?
      instructions:
      - text: Label vault {slug} as {label}.
        slots:
          slug: requestBody.slug
          label: requestBody.label
      - text: Register the name {label} for slug {slug}.
        slots:
          label: requestBody.label
          slug: requestBody.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/vault/visits/labels'].get
  update:
    x-apievangelist-phrasing:
      intent: List vault slug labels
      effect: read
      questions:
      - Which human-readable names are mapped to each vault slug?
      - Can I see both code-defined and runtime vault labels?
      instructions:
      - text: List all vault slug labels.
      - text: Show every slug-to-label mapping.
      method: generated
      generated: '2026-09-26'