# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Bitly Bitlinks API
  version: 1.0.0
extends: openapi/bitly-bitlinks-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: 21
- target: $.paths['/shorten'].post
  update:
    x-apievangelist-phrasing:
      intent: Shorten a long URL
      effect: write
      questions:
      - How do I shorten a long URL with Bitly?
      - Can I shorten a link on my own branded domain instead of bit.ly?
      - Why would shortening fail with a monthly branded link limit error?
      instructions:
      - text: Shorten {long_url}.
        slots:
          long_url: requestBody.long_url
      - text: Shorten {long_url} on domain {domain} in group {group_guid}.
        slots:
          long_url: requestBody.long_url
          domain: requestBody.domain
          group_guid: requestBody.group_guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/bitlinks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Bitlink with title, tags and options
      effect: write
      questions:
      - Can I set a title, tags and an expiration date at the moment I create a short link?
      - Is there a way to create a link with deeplinks or dynamic routing rules in one call?
      - How long can a new Bitlink be set to live before it expires?
      instructions:
      - text: Create a Bitlink for {long_url} titled {title} and tagged {tags}.
        slots:
          long_url: requestBody.long_url
          title: requestBody.title
          tags: requestBody.tags
      - text: Create a short link for {long_url} that expires at {expiration_at}.
        slots:
          long_url: requestBody.long_url
          expiration_at: requestBody.expiration_at
      - text: Add a keyword override {keyword} to existing Bitlink {bitlink_id}.
        slots:
          keyword: requestBody.keyword
          bitlink_id: requestBody.bitlink_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/bitlinks/{bitlink}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Bitlink's details
      effect: read
      questions:
      - What title, tags and destination does one of my short links have?
      - Can I look up when a particular Bitlink was created and whether it is archived?
      instructions:
      - text: Show the details of Bitlink {bitlink}.
        slots:
          bitlink: path.bitlink
      - text: Get the title, tags and settings for {bitlink}.
        slots:
          bitlink: path.bitlink
      method: generated
      generated: '2026-09-26'
- target: $.paths['/bitlinks/{bitlink}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an unedited Bitlink
      effect: destructive
      questions:
      - Can I delete a short link I created by mistake?
      - Which Bitlinks are allowed to be deleted?
      instructions:
      - text: Delete Bitlink {bitlink}.
        slots:
          bitlink: path.bitlink
      - text: Permanently remove the unedited short link {bitlink}.
        slots:
          bitlink: path.bitlink
      method: generated
      generated: '2026-09-26'
- target: $.paths['/bitlinks/{bitlink}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit or redirect a Bitlink
      effect: write
      questions:
      - How do I change where an existing short link redirects to?
      - Can I archive a single Bitlink or change its title after creating it?
      - Does redirecting an existing link count against my encode limit?
      instructions:
      - text: Redirect existing Bitlink {bitlink} to {long_url}.
        slots:
          bitlink: path.bitlink
          long_url: requestBody.long_url
      - text: Rename Bitlink {bitlink} to {title}.
        slots:
          bitlink: path.bitlink
          title: requestBody.title
      - text: Set archived to {archived} on the single link {bitlink}.
        slots:
          archived: requestBody.archived
          bitlink: path.bitlink
      method: generated
      generated: '2026-09-26'
- target: $.paths['/expand'].post
  update:
    x-apievangelist-phrasing:
      intent: Expand a short link to its long URL
      effect: read
      questions:
      - What long URL does a bit.ly short link point to?
      - Can I unshorten a Bitlink without opening it in a browser?
      instructions:
      - text: Expand {bitlink_id} and tell me the destination.
        slots:
          bitlink_id: requestBody.bitlink_id
      - text: Unshorten the link {bitlink_id}.
        slots:
          bitlink_id: requestBody.bitlink_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/bitlinks/{bitlink}/clicks'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Bitlink's clicks over time
      effect: read
      questions:
      - How many clicks did my short link get each day this week?
      - Can I see a click timeline for a link rather than just a total?
      instructions:
      - text: Show clicks per {unit} on {bitlink} for the last {units} periods.
        slots:
          unit: query.unit
          bitlink: path.bitlink
          units: query.units
      - text: Chart daily clicks for {bitlink} ending at {unit_reference}.
        slots:
          bitlink: path.bitlink
          unit_reference: query.unit_reference
      method: generated
      generated: '2026-09-26'
- target: $.paths['/bitlinks/{bitlink}/clicks/summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Bitlink's total clicks
      effect: read
      questions:
      - What is the total number of clicks on one of my links?
      - Can I get a single click total for a link over the past month?
      instructions:
      - text: Give me the total click count for {bitlink} over the last {units} {unit}s.
        slots:
          bitlink: path.bitlink
          units: query.units
          unit: query.unit
      - text: Total up every click on {bitlink} across all time, bucketed by {unit}.
        slots:
          bitlink: path.bitlink
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/bitlinks/{bitlink}/engagements'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Bitlink's engagements over time
      effect: read
      questions:
      - Can I see clicks, QR scans and button clicks for a link broken out per day?
      - What does engagement over time look like for one link, including scans?
      instructions:
      - text: Show engagement counts per {unit} for {bitlink} over the last {units} periods.
        slots:
          unit: query.unit
          bitlink: path.bitlink
          units: query.units
      - text: Chart clicks, scans and button clicks for {bitlink} by {unit}.
        slots:
          bitlink: path.bitlink
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/bitlinks/{bitlink}/engagements/summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Bitlink's total engagements
      effect: read
      questions:
      - What is the combined total of clicks and scans on one link?
      - Can I get a single engagement number for a link over a period?
      instructions:
      - text: Give me the total engagements for {bitlink} over the last {units} {unit}s.
        slots:
          bitlink: path.bitlink
          units: query.units
          unit: query.unit
      - text: Sum all clicks and scans on {bitlink} into one engagement total by {unit}.
        slots:
          bitlink: path.bitlink
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/bitlinks/{bitlink}/countries'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Bitlink's clicks by country
      effect: read
      questions:
      - Which countries are the clicks on my short link coming from?
      - Can I see the top countries clicking a specific link?
      instructions:
      - text: Break down clicks on {bitlink} by country over the last {units} {unit}s.
        slots:
          bitlink: path.bitlink
          units: query.units
          unit: query.unit
      - text: Show the top {size} countries clicking {bitlink} by {unit}.
        slots:
          size: query.size
          bitlink: path.bitlink
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/bitlinks/{bitlink}/cities'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Bitlink's clicks by city
      effect: read
      questions:
      - What cities are people clicking my link from?
      - Can I find the top cities for traffic on one short link?
      instructions:
      - text: Break down clicks on {bitlink} by city over the last {units} {unit}s.
        slots:
          bitlink: path.bitlink
          units: query.units
          unit: query.unit
      - text: List the top {size} cities clicking {bitlink} by {unit}.
        slots:
          size: query.size
          bitlink: path.bitlink
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/bitlinks/{bitlink}/devices'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Bitlink's clicks by device type
      effect: read
      questions:
      - Are people clicking my link mostly on mobile or desktop?
      - Which device types generate the clicks on a specific Bitlink?
      instructions:
      - text: Break down clicks on {bitlink} by device type over the last {units} {unit}s.
        slots:
          bitlink: path.bitlink
          units: query.units
          unit: query.unit
      - text: Show mobile versus desktop clicks for {bitlink} by {unit}.
        slots:
          bitlink: path.bitlink
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/bitlinks/{bitlink}/referrers'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Bitlink's clicks by referrer
      effect: read
      questions:
      - Which referring sources are sending clicks to my link?
      - Can I see referrer click counts for one short link?
      instructions:
      - text: Break down clicks on {bitlink} by referrer over the last {units} {unit}s.
        slots:
          bitlink: path.bitlink
          units: query.units
          unit: query.unit
      - text: List the top {size} referrers for {bitlink} by {unit}.
        slots:
          size: query.size
          bitlink: path.bitlink
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/bitlinks/{bitlink}/referrer_name'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Bitlink's clicks by referrer name
      effect: read
      questions:
      - Can I see my link's referrer clicks grouped by the referrer's name, like a named app or site?
      - What named referrers are driving clicks to a Bitlink?
      instructions:
      - text: Group clicks on {bitlink} by referrer name over the last {units} {unit}s.
        slots:
          bitlink: path.bitlink
          units: query.units
          unit: query.unit
      - text: Show the top {size} referrer names for {bitlink} by {unit}.
        slots:
          size: query.size
          bitlink: path.bitlink
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/bitlinks/{bitlink}/referring_domains'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Bitlink's clicks by referring domain
      effect: read
      questions:
      - Which websites (domains) are linking visitors to my short link?
      - Can I rank referring domains for one Bitlink by click count?
      instructions:
      - text: Break down clicks on {bitlink} by referring domain over the last {units} {unit}s.
        slots:
          bitlink: path.bitlink
          units: query.units
          unit: query.unit
      - text: List the top {size} referring domains for {bitlink} by {unit}.
        slots:
          size: query.size
          bitlink: path.bitlink
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/bitlinks/{bitlink}/referrers_by_domains'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Bitlink's referrers grouped by domain
      effect: read
      questions:
      - Can I see the individual referrers for my link nested under each referring domain?
      - What pages within each referring domain are sending clicks to a link?
      instructions:
      - text: Show referrers for {bitlink} grouped under their domains over the last {units} {unit}s.
        slots:
          bitlink: path.bitlink
          units: query.units
          unit: query.unit
      - text: Group the referrer URLs clicking {bitlink} by domain, per {unit}.
        slots:
          bitlink: path.bitlink
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/bitlinks'].get
  update:
    x-apievangelist-phrasing:
      intent: List and search a group's Bitlinks
      effect: read
      questions:
      - How do I list all the short links in one of my groups?
      - Can I search my links by tag, campaign or creation date?
      - Is there a way to find only links that have expired or have QR codes?
      instructions:
      - text: List the Bitlinks in group {group_guid}.
        slots:
          group_guid: path.group_guid
      - text: Search group {group_guid} for links matching {query}.
        slots:
          group_guid: path.group_guid
          query: query.query
      - text: Find links in group {group_guid} tagged {tags} and created after {created_after}.
        slots:
          group_guid: path.group_guid
          tags: query.tags
          created_after: query.created_after
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/bitlinks'].patch
  update:
    x-apievangelist-phrasing:
      intent: Bulk archive or retag up to 100 Bitlinks
      effect: write
      questions:
      - Can I archive a batch of short links at once instead of one by one?
      - How do I add or remove a tag across many links in a group?
      - What is the maximum number of links a bulk update can touch?
      instructions:
      - text: 'Archive these links in group {group_guid}: {links}.'
        slots:
          group_guid: path.group_guid
          links: requestBody.links
      - text: In group {group_guid}, add tags {add_tags} to links {links}.
        slots:
          group_guid: path.group_guid
          add_tags: requestBody.add_tags
          links: requestBody.links
      - text: Remove tags {remove_tags} from the Bitlinks {links} in group {group_guid}.
        slots:
          remove_tags: requestBody.remove_tags
          links: requestBody.links
          group_guid: path.group_guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/engagements/sorted/top'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank a group's links and standalone QR codes by engagement
      effect: read
      questions:
      - Which links and standalone QR codes in my group got the most engagement, ranked together?
      - Can I compare decoupled QR codes and Bitlinks in a single top-performers list?
      instructions:
      - text: Rank the top {size} links and decoupled QR codes in group {group_guid} by engagement.
        slots:
          size: query.size
          group_guid: path.group_guid
      - text: Show group {group_guid}'s combined link and standalone QR code leaderboard for the last {units} {unit}s.
        slots:
          group_guid: path.group_guid
          units: query.units
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/bitlinks/{sort}'].get
  update:
    x-apievangelist-phrasing:
      intent: List a group's Bitlinks sorted by clicks
      effect: read
      questions:
      - Which of my short links in a group got the most clicks?
      - Can I get a group's Bitlinks back sorted rather than newest first?
      instructions:
      - text: List group {group_guid}'s Bitlinks sorted by {sort}.
        slots:
          group_guid: path.group_guid
          sort: path.sort
      - text: Show the top {size} links in group {group_guid} sorted by {sort} over the last {units} {unit}s.
        slots:
          size: query.size
          group_guid: path.group_guid
          sort: path.sort
          units: query.units
          unit: query.unit
      method: generated
      generated: '2026-09-26'