# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Bitly Groups API
  version: 1.0.0
extends: openapi/bitly-groups-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: 28
- target: $.paths['/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List groups
      effect: read
      questions:
      - What groups do I have access to in Bitly?
      - Can I list only the groups inside one organization?
      instructions:
      - text: List all my groups.
      - text: Show the groups in organization {organization_guid}.
        slots:
          organization_guid: query.organization_guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group's details
      effect: read
      questions:
      - Which organization and branded domains does a particular group use?
      - How do I look up a single group by its GUID?
      instructions:
      - text: Show group {group_guid}.
        slots:
          group_guid: path.group_guid
      - text: Fetch the name, organization and domains of group {group_guid}.
        slots:
          group_guid: path.group_guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename a group or change its domains
      effect: write
      questions:
      - Can I rename one of my groups?
      - How do I change which branded short domains a group can use?
      instructions:
      - text: Rename group {group_guid} to {name}.
        slots:
          group_guid: path.group_guid
          name: requestBody.name
      - text: Set the branded short domains for group {group_guid} to {bsds}.
        slots:
          group_guid: path.group_guid
          bsds: requestBody.bsds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List tags used in a group
      effect: read
      questions:
      - What tags are my team using on links in a group?
      - Can I get the tags used on QR codes instead of links, and is there a cap on how many come back?
      instructions:
      - text: List the tags used in group {group_guid}.
        slots:
          group_guid: path.group_guid
      - text: Show group {group_guid}'s {type} tags.
        slots:
          group_guid: path.group_guid
          type: query.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/preferences'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group's preferences
      effect: read
      questions:
      - Which domain does a group shorten links with by default?
      - Where can I see a group's saved preferences?
      instructions:
      - text: Show the preferences for group {group_guid}.
        slots:
          group_guid: path.group_guid
      - text: Tell me which default domain group {group_guid} prefers.
        slots:
          group_guid: path.group_guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/preferences'].patch
  update:
    x-apievangelist-phrasing:
      intent: Set a group's default domain
      effect: write
      questions:
      - How do I make a group shorten links on my branded domain by default?
      - Can I change a group's preferred short domain?
      instructions:
      - text: Set group {group_guid}'s default domain to {domain_preference}.
        slots:
          group_guid: path.group_guid
          domain_preference: requestBody.domain_preference
      - text: Change the preferred short domain for group {group_guid} to {domain_preference}.
        slots:
          group_guid: path.group_guid
          domain_preference: requestBody.domain_preference
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/shorten_counts'].get
  update:
    x-apievangelist-phrasing:
      intent: Count links shortened in a group over time
      effect: read
      questions:
      - How many links has one group shortened per day recently?
      - Can I track a group's link creation volume over time?
      instructions:
      - text: Show how many links group {group_guid} shortened per {unit} over the last {units} periods.
        slots:
          group_guid: path.group_guid
          unit: query.unit
          units: query.units
      - text: Get group {group_guid}'s shorten counts for all time by {unit}.
        slots:
          group_guid: path.group_guid
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/countries'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group's click traffic by country
      effect: read
      questions:
      - Which countries does the click traffic across a whole group come from?
      - Can I see the geographic origin of clicks for a group, by country?
      instructions:
      - text: Show where group {group_guid}'s click traffic originates, by country, over the last {units} {unit}s.
        slots:
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      - text: Get the top {size} origin countries for clicks in group {group_guid} by {unit}.
        slots:
          size: query.size
          group_guid: path.group_guid
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/cities'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group's click traffic by city
      effect: read
      questions:
      - What cities does a group's overall click traffic originate from?
      - Can I map a group's click origins at city level?
      instructions:
      - text: Show where group {group_guid}'s click traffic originates, by city, over the last {units} {unit}s.
        slots:
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      - text: Get the top {size} origin cities for clicks in group {group_guid} by {unit}.
        slots:
          size: query.size
          group_guid: path.group_guid
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/devices'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group's click traffic by device type
      effect: read
      questions:
      - What mix of device types generates the click traffic for a group?
      - Is a group's audience clicking mostly on phones or computers?
      instructions:
      - text: Show the device types generating click traffic for group {group_guid} over the last {units} {unit}s.
        slots:
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      - text: Get group {group_guid}'s click traffic device mix, top {size}, by {unit}.
        slots:
          group_guid: path.group_guid
          size: query.size
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/referring_networks'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group's clicks by referring network
      effect: read
      questions:
      - Which social networks and referring networks drive clicks to a group's links?
      - Can I see group click metrics broken down by referring network?
      instructions:
      - text: Break down group {group_guid}'s clicks by referring network over the last {units} {unit}s.
        slots:
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      - text: List the top {size} referring networks for group {group_guid} by {unit}.
        slots:
          size: query.size
          group_guid: path.group_guid
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/referrers'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group's click traffic by referrer
      effect: read
      questions:
      - Which referrers send the most click traffic to a group overall?
      - Can I get group-wide click metrics by referrer?
      instructions:
      - text: Show group {group_guid}'s click traffic metrics by referrer over the last {units} {unit}s.
        slots:
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      - text: Get the top {size} referrers of click traffic in group {group_guid} by {unit}.
        slots:
          size: query.size
          group_guid: path.group_guid
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/engagements/top'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank a group's links by engagement
      effect: read
      questions:
      - Which links in my group have the most engagement, counting clicks and scans?
      - Can I get the top performing links in a group by engagement?
      instructions:
      - text: Show the top {size} links by engagement in group {group_guid} over the last {units} {unit}s.
        slots:
          size: query.size
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      - text: Rank group {group_guid}'s links by engagement per {unit}.
        slots:
          group_guid: path.group_guid
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/engagements/over_time'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group's engagements over time
      effect: read
      questions:
      - How has engagement across all links in a group trended week to week?
      - Can I chart a group's total engagements over time?
      instructions:
      - text: Chart engagements per {unit} for all links in group {group_guid} over the last {units} periods.
        slots:
          unit: query.unit
          group_guid: path.group_guid
          units: query.units
      - text: Show group {group_guid}'s engagement trend ending {unit_reference}.
        slots:
          group_guid: path.group_guid
          unit_reference: query.unit_reference
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/clicks'].get
  update:
    x-apievangelist-phrasing:
      intent: Count clicks on a group's Bitlinks
      effect: read
      questions:
      - How many clicks have all the Bitlinks in a group received?
      - What is the click count for a group over the last 30 days?
      instructions:
      - text: Count clicks on the Bitlinks in group {group_guid} for the last {units} {unit}s.
        slots:
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      - text: Get the group click count for {group_guid} by {unit}.
        slots:
          group_guid: path.group_guid
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/exports'].post
  update:
    x-apievangelist-phrasing:
      intent: Export a group's links, QR codes or metrics as CSV
      effect: read
      questions:
      - Can I download a CSV of all the links or QR codes in a group?
      - How many rows can a CSV export include, and what happens when there are more?
      - Is there a way to export engagement metrics for a specific list of Bitlinks?
      instructions:
      - text: Export group {group_guid} as a {export_type} CSV.
        slots:
          group_guid: path.group_guid
          export_type: requestBody.export_type
      - text: Export engagement metrics for {bitlinks} in group {group_guid} as CSV, as {export_type}, from {unix_from} to {unix_to}.
        slots:
          bitlinks: requestBody.bitlinks
          group_guid: path.group_guid
          export_type: requestBody.export_type
          unix_from: requestBody.unix_from
          unix_to: requestBody.unix_to
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/feature_usage'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a group's current feature limit usage
      effect: read
      questions:
      - How much of each feature limit has a group used so far?
      - Can I check a group's current usage for just one named limit?
      instructions:
      - text: Show group {group_guid}'s current feature limit usage.
        slots:
          group_guid: path.group_guid
      - text: Check current usage of the {name} limit for group {group_guid}.
        slots:
          name: query.name
          group_guid: path.group_guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/historical_usage'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group's historical limit usage
      effect: read
      questions:
      - How did a group's usage of a limit change over past months?
      - Can I see daily, weekly or monthly usage history between two dates?
      instructions:
      - text: Show group {group_guid}'s historical {name} usage from {start_date} to {end_date}.
        slots:
          group_guid: path.group_guid
          name: query.name
          start_date: query.start_date
          end_date: query.end_date
      - text: Get monthly-style usage history for limit {name} in group {group_guid}, grouped by {unit}.
        slots:
          name: query.name
          group_guid: path.group_guid
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/links/clicks/over_time'].get
  update:
    x-apievangelist-phrasing:
      intent: Chart link clicks over time for a group
      effect: read
      questions:
      - Can I chart link clicks per day across every link in a group?
      - What does the link-clicks timeline look like for a whole group?
      instructions:
      - text: Chart link clicks per {unit} for all links in group {group_guid} over the last {units} periods.
        slots:
          unit: query.unit
          group_guid: path.group_guid
          units: query.units
      - text: Show group {group_guid}'s link-click timeline ending {unit_reference}.
        slots:
          group_guid: path.group_guid
          unit_reference: query.unit_reference
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/links/clicks/devices'].get
  update:
    x-apievangelist-phrasing:
      intent: Get link clicks by device for a group's links
      effect: read
      questions:
      - In the link-clicks report for a group, how do clicks split across devices?
      - Can I see link clicks by device for all links in a group?
      instructions:
      - text: Break down link clicks for every link in group {group_guid} by device, last {units} {unit}s.
        slots:
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      - text: Get the link-clicks-by-device report for group {group_guid}, top {size}, by {unit}.
        slots:
          group_guid: path.group_guid
          size: query.size
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/links/clicks/referrers'].get
  update:
    x-apievangelist-phrasing:
      intent: Get link clicks by referrer for a group's links
      effect: read
      questions:
      - In the link-clicks report, which referrers account for clicks on all of a group's links?
      - Can I pull link clicks by referrer across every link in a group?
      instructions:
      - text: Break down link clicks for every link in group {group_guid} by referrer, last {units} {unit}s.
        slots:
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      - text: Get the link-clicks-by-referrer report for group {group_guid}, top {size}, by {unit}.
        slots:
          group_guid: path.group_guid
          size: query.size
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/links/clicks/countries'].get
  update:
    x-apievangelist-phrasing:
      intent: Get link clicks by country for a group's links
      effect: read
      questions:
      - In the link-clicks report, how are clicks on all of a group's links spread across countries?
      - Can I pull link clicks by country for every link in a group?
      instructions:
      - text: Break down link clicks for every link in group {group_guid} by country, last {units} {unit}s.
        slots:
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      - text: Get the link-clicks-by-country report for group {group_guid}, top {size}, by {unit}.
        slots:
          group_guid: path.group_guid
          size: query.size
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/links/clicks/cities'].get
  update:
    x-apievangelist-phrasing:
      intent: Get link clicks by city for a group's links
      effect: read
      questions:
      - In the link-clicks report, which cities do clicks on a group's links come from?
      - Can I pull link clicks by city for every link in a group?
      instructions:
      - text: Break down link clicks for every link in group {group_guid} by city, last {units} {unit}s.
        slots:
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      - text: Get the link-clicks-by-city report for group {group_guid}, top {size}, by {unit}.
        slots:
          group_guid: path.group_guid
          size: query.size
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/links/clicks/top'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank a group's links by clicks
      effect: read
      questions:
      - Which links in a group got the most clicks, not counting scans?
      - Can I get the top performing links in a group ranked by click count?
      instructions:
      - text: Show the top {size} links by clicks in group {group_guid} over the last {units} {unit}s.
        slots:
          size: query.size
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      - text: Rank group {group_guid}'s links by click count per {unit}.
        slots:
          group_guid: path.group_guid
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/codes/scans/over_time'].get
  update:
    x-apievangelist-phrasing:
      intent: Chart QR code scans over time for a group
      effect: read
      questions:
      - How have QR code scans across a group trended over time?
      - Can I chart daily scans for all of a group's QR codes?
      instructions:
      - text: Chart QR code scans per {unit} for group {group_guid} over the last {units} periods.
        slots:
          unit: query.unit
          group_guid: path.group_guid
          units: query.units
      - text: Show group {group_guid}'s QR scan timeline ending {unit_reference}.
        slots:
          group_guid: path.group_guid
          unit_reference: query.unit_reference
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/codes/scans/countries'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group's QR code scans by country
      effect: read
      questions:
      - Which countries are a group's QR codes scanned in?
      - Can I break down all QR scans in a group by country?
      instructions:
      - text: Break down QR code scans in group {group_guid} by country over the last {units} {unit}s.
        slots:
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      - text: Show group {group_guid}'s QR scans per country by {unit}.
        slots:
          group_guid: path.group_guid
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/codes/scans/cities'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a group's QR code scans by city
      effect: read
      questions:
      - In which cities are a group's QR codes being scanned?
      - Can I break down all QR scans in a group by city?
      instructions:
      - text: List the cities where QR codes in group {group_guid} were scanned during the last {units} {unit}s.
        slots:
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      - text: Show group {group_guid}'s QR scans per city by {unit}.
        slots:
          group_guid: path.group_guid
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/codes/scans/top'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank a group's QR codes by scans
      effect: read
      questions:
      - Which QR codes in my group are scanned the most?
      - Can I rank only standalone (decoupled) QR codes by scan count?
      instructions:
      - text: Show the top-scanned QR codes in group {group_guid} over the last {units} {unit}s.
        slots:
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      - text: Rank group {group_guid}'s QR codes by decoupled scan count, with decoupled set to {decoupled}, by {unit}.
        slots:
          group_guid: path.group_guid
          decoupled: query.decoupled
          unit: query.unit
      method: generated
      generated: '2026-09-26'