# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Bitly Custom Bitlinks API
  version: 1.0.0
extends: openapi/bitly-custom-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: 5
- target: $.paths['/custom_bitlinks'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a custom back-half to a Bitlink
      effect: write
      questions:
      - How do I give a short link a memorable custom back-half on my branded domain?
      - Does a custom keyword have to use the same domain as the Bitlink it points to?
      instructions:
      - text: Add the custom back-half {custom_bitlink} to Bitlink {bitlink_id}.
        slots:
          custom_bitlink: requestBody.custom_bitlink
          bitlink_id: requestBody.bitlink_id
      - text: Create custom link {custom_bitlink} that redirects through {bitlink_id}.
        slots:
          custom_bitlink: requestBody.custom_bitlink
          bitlink_id: requestBody.bitlink_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/custom_bitlinks/{custom_bitlink}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom Bitlink and its history
      effect: read
      questions:
      - Where does my custom keyword link currently point, and where did it point before?
      - Can I see the redirect history of a custom back-half?
      instructions:
      - text: Show custom Bitlink {custom_bitlink} and its history.
        slots:
          custom_bitlink: path.custom_bitlink
      - text: Look up which Bitlink the keyword {custom_bitlink} is attached to.
        slots:
          custom_bitlink: path.custom_bitlink
      method: generated
      generated: '2026-09-26'
- target: $.paths['/custom_bitlinks/{custom_bitlink}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Move a custom back-half to a different Bitlink
      effect: write
      questions:
      - Can I repoint my custom keyword to a different short link without changing the keyword?
      - How do I move a custom back-half from one Bitlink to another?
      instructions:
      - text: Move custom keyword {custom_bitlink} to Bitlink {bitlink_id}.
        slots:
          custom_bitlink: path.custom_bitlink
          bitlink_id: requestBody.bitlink_id
      - text: Repoint {custom_bitlink} so it redirects via {bitlink_id} instead.
        slots:
          custom_bitlink: path.custom_bitlink
          bitlink_id: requestBody.bitlink_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/custom_bitlinks/{custom_bitlink}/clicks_by_destination'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom Bitlink's clicks by destination
      effect: read
      questions:
      - After I moved my custom keyword, how many clicks went to each past destination?
      - Can I split a custom link's clicks by the URLs it has redirected to over time?
      instructions:
      - text: Break down clicks on custom link {custom_bitlink} by each historical destination over the last {units} {unit}s.
        slots:
          custom_bitlink: path.custom_bitlink
          units: query.units
          unit: query.unit
      - text: Show per-destination click totals for {custom_bitlink} for all time, grouped by {unit}.
        slots:
          custom_bitlink: path.custom_bitlink
          unit: query.unit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/custom_bitlinks/{custom_bitlink}/clicks'].get
  update:
    x-apievangelist-phrasing:
      intent: Get click counts over a custom Bitlink's whole history
      effect: read
      questions:
      - How many clicks has my custom keyword link had across its entire history?
      - Can I chart daily clicks on a custom back-half, including before it was moved?
      instructions:
      - text: Show clicks per {unit} on custom link {custom_bitlink} for the last {units} periods.
        slots:
          unit: query.unit
          custom_bitlink: path.custom_bitlink
          units: query.units
      - text: Get the full-history click timeline for custom keyword {custom_bitlink} by {unit}.
        slots:
          custom_bitlink: path.custom_bitlink
          unit: query.unit
      method: generated
      generated: '2026-09-26'