# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Live Direct Marketing Online Tracking API
  version: 1.0.0
extends: openapi/live-direct-marketing-online-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: 17
- target: $.paths['/api/t/o/{trackingId}.gif'].get
  update:
    x-apievangelist-phrasing:
      intent: Serve the open-tracking pixel and log an open
      effect: write
      questions:
      - How are email opens recorded when a recipient loads the image?
      - What happens when the 1x1 tracking pixel in a campaign email is requested?
      instructions:
      - text: Load the open pixel for tracking id {trackingId} to log an open.
        slots:
          trackingId: path.trackingId
      - text: Record an email open for {trackingId} via the tracking GIF.
        slots:
          trackingId: path.trackingId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/t/c/{trackingId}/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Follow a tracked campaign click and log it
      effect: write
      questions:
      - How does a clicked link in a campaign email get logged before redirecting?
      - Do bots get sent to a decoy URL when they click a campaign link?
      instructions:
      - text: Open the campaign click link {slug} for tracking id {trackingId}.
        slots:
          slug: path.slug
          trackingId: path.trackingId
      - text: Follow tracked click {trackingId}/{slug} and record the CLICK.
        slots:
          trackingId: path.trackingId
          slug: path.slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/r/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Follow a short redirect link without logging
      effect: read
      questions:
      - Where does a short /r/ link I created directly send people?
      - Why don't clicks on my directly-created short links show up in analytics?
      instructions:
      - text: Resolve the short redirect link {slug}.
        slots:
          slug: path.slug
      - text: Follow the /r/{slug} short link with cloaking applied.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tracking/links'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a tracking link
      effect: write
      questions:
      - How do I create a short tracking link without sending a campaign?
      - Can I turn on bot cloaking or a captcha for a new link right away?
      instructions:
      - text: Create a tracking link pointing to our pricing page.
      - text: Make a new short link with bot_split cloaking and a decoy URL.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tracking/links/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a tracking link
      effect: read
      questions:
      - Where does a given tracking link point and is it cloaked?
      - How do I see the details of a short link by its slug?
      instructions:
      - text: Show the tracking link {slug}.
        slots:
          slug: path.slug
      - text: Get the target URL and cloak mode of link {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tracking/links/{slug}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a tracking link
      effect: destructive
      questions:
      - How do I remove a tracking link I no longer need?
      - Can I delete a short link by its slug?
      instructions:
      - text: Delete tracking link {slug}.
        slots:
          slug: path.slug
      - text: Remove the short link {slug} permanently.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tracking/links/{slug}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a tracking link's target or cloaking
      effect: write
      questions:
      - How do I change where an existing tracking link redirects?
      - Can I switch an existing link's cloak mode to captcha?
      instructions:
      - text: Point tracking link {slug} at a new target URL.
        slots:
          slug: path.slug
      - text: Turn off cloaking on link {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tracking/simulate-click'].post
  update:
    x-apievangelist-phrasing:
      intent: Test a link's cloaking decision without logging
      effect: read
      questions:
      - Would a given user agent be sent to the target, the decoy or a captcha?
      - Can I dry-run a link's bot cloaking without moving the click counters?
      instructions:
      - text: Simulate a click on my link with a crawler user agent and show the verdict.
      - text: Dry-run the cloaking decision for this link from a given IP.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tracking/events'].get
  update:
    x-apievangelist-phrasing:
      intent: List raw open and click tracking events
      effect: read
      questions:
      - Which opens and clicks did a specific contact generate?
      - Can I filter raw tracking events to bot clicks only within a date range?
      instructions:
      - text: List {type} tracking events for contact {contactId}.
        slots:
          type: query.type
          contactId: query.contactId
      - text: Show tracking events for dialog {dialogId} between {from} and {to}.
        slots:
          dialogId: query.dialogId
          from: query.from
          to: query.to
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tracking/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get tracking totals for a sending task
      effect: read
      questions:
      - How many opens and clicks did one sending task get?
      - Where are the aggregated tracking counts for a task?
      instructions:
      - text: Get the tracking stats for task {taskId}.
        slots:
          taskId: query.taskId
      - text: Total up opens and clicks for task {taskId}.
        slots:
          taskId: query.taskId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tracking/pixel-settings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get open-pixel tracking settings
      effect: read
      questions:
      - Is open-pixel tracking turned on for my workspace?
      - Which domain serves our tracking pixel?
      instructions:
      - text: Show our pixel tracking settings.
      - text: Fetch the workspace open-pixel configuration.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tracking/pixel-settings'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update open-pixel tracking settings
      effect: write
      questions:
      - How do I turn off open tracking pixels?
      - Can I change the source domain for our open pixel?
      instructions:
      - text: Disable open-pixel tracking for the workspace.
      - text: Update our pixel tracking settings to use our own domain.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tracking/analytics/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get open and click rates
      effect: read
      questions:
      - What open rate and click rate did a campaign task achieve?
      - How many unique opens and unique clicks came in over a date range?
      instructions:
      - text: Show open and click rates for task {taskId} from {from} to {to}.
        slots:
          taskId: query.taskId
          from: query.from
          to: query.to
      - text: Get unique opens and clicks for dialog {dialogId}.
        slots:
          dialogId: query.dialogId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tracking/analytics/timeline'].get
  update:
    x-apievangelist-phrasing:
      intent: Chart opens and clicks over time
      effect: read
      questions:
      - How did opens and clicks trend day by day for a task?
      - Can I get an opens and clicks timeline for the last 30 days?
      instructions:
      - text: Plot the opens and clicks timeline for task {taskId} over {days} days.
        slots:
          taskId: query.taskId
          days: query.days
      - text: Show daily engagement for task {taskId}.
        slots:
          taskId: query.taskId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tracking/analytics/top-links'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank the most clicked links
      effect: read
      questions:
      - Which links in my campaign got the most clicks?
      - What are the top clicked URLs for a task with their counts?
      instructions:
      - text: List the top {limit} clicked links for task {taskId}.
        slots:
          limit: query.limit
          taskId: query.taskId
      - text: Rank links by clicks for task {taskId}.
        slots:
          taskId: query.taskId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tracking/analytics/email-clients'].get
  update:
    x-apievangelist-phrasing:
      intent: Break down opens by email client
      effect: read
      questions:
      - Which email clients do my recipients open messages in?
      - What share of opens come from each mail app?
      instructions:
      - text: Show the email client distribution from tracking events.
      - text: Break down opens by mail client.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tracking/analytics/devices'].get
  update:
    x-apievangelist-phrasing:
      intent: Break down engagement by device type
      effect: read
      questions:
      - Do my recipients mostly read on mobile or desktop?
      - What is the device type split across tracking events?
      instructions:
      - text: Show the device type distribution of tracking events.
      - text: Break down engagement by mobile, desktop and tablet.
      method: generated
      generated: '2026-10-01'