# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Bitly QR Codes API
  version: 1.0.0
extends: openapi/bitly-qr-codes-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: 16
- target: $.paths['/qr-codes'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a saved QR code
      effect: write
      questions:
      - How do I create a trackable QR code that points to a URL?
      - Can I customize the colors and look of a QR code when I create it?
      - Is it possible to make a QR code that expires on a set date?
      instructions:
      - text: Create a QR code in group {group_guid} pointing to {destination}.
        slots:
          group_guid: requestBody.group_guid
          destination: requestBody.destination
      - text: Make a QR code titled {title} for {destination} in group {group_guid}, tagged {tags}.
        slots:
          title: requestBody.title
          destination: requestBody.destination
          group_guid: requestBody.group_guid
          tags: requestBody.tags
      - text: Create a QR code for {destination} in group {group_guid} that expires at {expiration_at}.
        slots:
          destination: requestBody.destination
          group_guid: requestBody.group_guid
          expiration_at: requestBody.expiration_at
      method: generated
      generated: '2026-09-26'
- target: $.paths['/qr-codes/static'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a one-off static QR code image
      effect: write
      questions:
      - Can I just generate a QR code image for some content without saving it in my account?
      - Which image formats can a static QR code be returned in?
      - Are logos and frames supported on static QR code images?
      instructions:
      - text: Generate a static QR code image encoding {content} for group {group_guid}.
        slots:
          content: requestBody.content
          group_guid: requestBody.group_guid
      - text: Render an unsaved {format} QR code of {content} using group {group_guid}.
        slots:
          format: query.format
          content: requestBody.content
          group_guid: requestBody.group_guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/qr-codes/{qrcode_id}/image'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a saved QR code's image
      effect: read
      questions:
      - How do I download the image for a QR code I already created?
      - Can I get an existing QR code as an SVG or a PNG?
      instructions:
      - text: Download the image for QR code {qrcode_id}.
        slots:
          qrcode_id: path.qrcode_id
      - text: Get QR code {qrcode_id}'s image as {format}.
        slots:
          qrcode_id: path.qrcode_id
          format: query.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/qr-codes/{qrcode_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a QR code's details
      effect: read
      questions:
      - What destination and settings does one of my QR codes have?
      - Can I look up a QR code's metadata by its ID?
      instructions:
      - text: Show the details of QR code {qrcode_id}.
        slots:
          qrcode_id: path.qrcode_id
      - text: Fetch the metadata for QR code {qrcode_id}.
        slots:
          qrcode_id: path.qrcode_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/qr-codes/{qrcode_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a QR code
      effect: destructive
      questions:
      - Can I delete a QR code I no longer use?
      - Does deleting a QR code also remove the short link behind it?
      instructions:
      - text: Delete QR code {qrcode_id}.
        slots:
          qrcode_id: path.qrcode_id
      - text: Remove QR code {qrcode_id} and its associated link.
        slots:
          qrcode_id: path.qrcode_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/qr-codes/{qrcode_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit a QR code's title, design or tags
      effect: write
      questions:
      - How do I change the design or title of a single existing QR code?
      - Can I set or change the expiration on one QR code after it is created?
      instructions:
      - text: Rename QR code {qrcode_id} to {title}.
        slots:
          qrcode_id: path.qrcode_id
          title: requestBody.title
      - text: Set the tags on QR code {qrcode_id} to {tags}.
        slots:
          qrcode_id: path.qrcode_id
          tags: requestBody.tags
      - text: Make QR code {qrcode_id} expire at {expiration_at}.
        slots:
          qrcode_id: path.qrcode_id
          expiration_at: requestBody.expiration_at
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/qr-codes'].get
  update:
    x-apievangelist-phrasing:
      intent: List and search a group's QR codes
      effect: read
      questions:
      - What QR codes exist in one of my groups?
      - Can I filter my QR codes to GS1 codes or ones with custom designs?
      - Which QR codes in a group were created by a particular teammate?
      instructions:
      - text: List the QR codes in group {group_guid}.
        slots:
          group_guid: path.group_guid
      - text: Search QR codes in group {group_guid} for {query}.
        slots:
          group_guid: path.group_guid
          query: query.query
      - text: Find QR codes in group {group_guid} created by {creating_login}.
        slots:
          group_guid: path.group_guid
          creating_login: query.creating_login
      method: generated
      generated: '2026-09-26'
- target: $.paths['/groups/{group_guid}/qr-codes'].patch
  update:
    x-apievangelist-phrasing:
      intent: Bulk archive or retag up to 100 QR codes
      effect: write
      questions:
      - Can I archive or unarchive many QR codes in one request?
      - Is there a way to tag a batch of QR codes at once, and are Pages codes included?
      instructions:
      - text: Archive the QR codes {qr_code_ids} in group {group_guid}.
        slots:
          qr_code_ids: requestBody.qr_code_ids
          group_guid: path.group_guid
      - text: Add tags {add_tags} to QR codes {qr_code_ids} in group {group_guid}.
        slots:
          add_tags: requestBody.add_tags
          qr_code_ids: requestBody.qr_code_ids
          group_guid: path.group_guid
      - text: Strip tags {remove_tags} from QR codes {qr_code_ids} in group {group_guid}.
        slots:
          remove_tags: requestBody.remove_tags
          qr_code_ids: requestBody.qr_code_ids
          group_guid: path.group_guid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/qr-codes/{qrcode_id}/scans'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a QR code's scans over time
      effect: read
      questions:
      - How many times was my QR code scanned each day?
      - Can I see a scan timeline for one QR code?
      instructions:
      - text: Show scans per {unit} for QR code {qrcode_id} over the last {units} periods.
        slots:
          unit: query.unit
          qrcode_id: path.qrcode_id
          units: query.units
      - text: Chart the scan history of QR code {qrcode_id} by {unit}.
        slots:
          qrcode_id: path.qrcode_id
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/qr-codes/{qrcode_id}/scans/summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a QR code's total scans
      effect: read
      questions:
      - What is the total scan count for one of my QR codes?
      - Can I get a single scan total for a QR code over the past week?
      instructions:
      - text: Give me the total scans for QR code {qrcode_id} over the last {units} {unit}s.
        slots:
          qrcode_id: path.qrcode_id
          units: query.units
          unit: query.unit
      - text: Sum all scans of QR code {qrcode_id} into one number, by {unit}.
        slots:
          qrcode_id: path.qrcode_id
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/qr-codes/{qrcode_id}/scans/countries'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a QR code's scans by country
      effect: read
      questions:
      - Which countries is my QR code being scanned in?
      - Can I rank countries by scans for one QR code?
      instructions:
      - text: Break down scans of QR code {qrcode_id} by country over the last {units} {unit}s.
        slots:
          qrcode_id: path.qrcode_id
          units: query.units
          unit: query.unit
      - text: List the top {size} countries scanning QR code {qrcode_id} by {unit}.
        slots:
          size: query.size
          qrcode_id: path.qrcode_id
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/qr-codes/{qrcode_id}/scans/cities'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a QR code's scans by city
      effect: read
      questions:
      - In which cities are people scanning my QR code?
      - Can I see the top cities for scans of one QR code?
      instructions:
      - text: Break down scans of QR code {qrcode_id} by city over the last {units} {unit}s.
        slots:
          qrcode_id: path.qrcode_id
          units: query.units
          unit: query.unit
      - text: List the top {size} cities scanning QR code {qrcode_id} by {unit}.
        slots:
          size: query.size
          qrcode_id: path.qrcode_id
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/qr-codes/{qrcode_id}/scans/device_os'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a QR code's scans by device OS
      effect: read
      questions:
      - Are my QR code scans coming mostly from iOS or Android?
      - Which device operating systems scan a given QR code?
      instructions:
      - text: Break down scans of QR code {qrcode_id} by device operating system over the last {units} {unit}s.
        slots:
          qrcode_id: path.qrcode_id
          units: query.units
          unit: query.unit
      - text: Show the top {size} device OSes scanning QR code {qrcode_id} by {unit}.
        slots:
          size: query.size
          qrcode_id: path.qrcode_id
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/qr-codes/{qrcode_id}/scans/browsers'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a QR code's scans by browser
      effect: read
      questions:
      - Which browsers open my QR code after it is scanned?
      - Can I see scan counts per browser for one QR code?
      instructions:
      - text: Break down scans of QR code {qrcode_id} by browser over the last {units} {unit}s.
        slots:
          qrcode_id: path.qrcode_id
          units: query.units
          unit: query.unit
      - text: Show the top {size} browsers for QR code {qrcode_id} scans by {unit}.
        slots:
          size: query.size
          qrcode_id: path.qrcode_id
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/qr-codes/{qrcode_id}/to-bitlink'].put
  update:
    x-apievangelist-phrasing:
      intent: Couple a standalone QR code to a Bitlink
      effect: write
      questions:
      - How do I attach a standalone QR code to its own Bitly short link?
      - Does upgrading a decoupled QR code use up one of my monthly link encodes?
      instructions:
      - text: Upgrade standalone QR code {qrcode_id} to a coupled Bitlink.
        slots:
          qrcode_id: path.qrcode_id
      - text: Associate decoupled QR code {qrcode_id} with its underlying short link.
        slots:
          qrcode_id: path.qrcode_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/qr-codes/{qrcode_id}/redirect'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a standalone QR code's destination URL
      effect: write
      questions:
      - Can I change where a standalone QR code sends people after it has been printed?
      - Why can't I redirect a QR code that is tied to a Bitlink this way?
      instructions:
      - text: Redirect standalone QR code {qrcode_id} to {long_url}.
        slots:
          qrcode_id: path.qrcode_id
          long_url: requestBody.long_url
      - text: Point decoupled QR code {qrcode_id} at the new destination {long_url}.
        slots:
          qrcode_id: path.qrcode_id
          long_url: requestBody.long_url
      method: generated
      generated: '2026-09-26'