# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Sendcloud Parcels API
  version: 1.0.0
extends: openapi/sendcloud-parcels-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: 9
- target: $.paths['/insights/parcels/series'].get
  update:
    x-apievangelist-phrasing:
      intent: Chart parcel volume over time
      effect: read
      questions:
      - How many parcels did I ship per day last month?
      - Can I see my parcel volume per month for a carrier?
      instructions:
      - text: Show parcel counts per {granularity} from {start_date} to {end_date}.
        slots:
          granularity: query.granularity
          start_date: query.start_date
          end_date: query.end_date
      - text: Chart {carrier_code} parcels per {granularity} between {start_date} and {end_date}.
        slots:
          carrier_code: query.carrier_code
          granularity: query.granularity
          start_date: query.start_date
          end_date: query.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/insights/parcels/buckets'].get
  update:
    x-apievangelist-phrasing:
      intent: Group parcel counts by a category
      effect: read
      questions:
      - Which destination countries receive the most of my parcels?
      - Can I break down parcel volume by carrier for a period?
      instructions:
      - text: Group parcels from {start_date} to {end_date} by {group_by}.
        slots:
          start_date: query.start_date
          end_date: query.end_date
          group_by: query.group_by
      - text: Show the top {size} {group_by} buckets for parcels between {start_date} and {end_date}.
        slots:
          size: query.size
          group_by: query.group_by
          start_date: query.start_date
          end_date: query.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/insights/parcels/counts-summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Count parcels for the last N days
      effect: read
      questions:
      - How many parcels have I sent in the last 30 days?
      - What is my recent incoming parcel count?
      instructions:
      - text: Count my parcels for the last {last_days} days.
        slots:
          last_days: query.last_days
      - text: Summarize {direction} parcels over the last {last_days} days.
        slots:
          direction: query.direction
          last_days: query.last_days
      method: generated
      generated: '2026-10-01'
- target: $.paths['/parcels'].get
  update:
    x-apievangelist-phrasing:
      intent: List parcels
      effect: read
      questions:
      - Which parcels have I created or imported into my account?
      - Can I find parcels updated since a certain date?
      - Is there a way to look up a parcel by its order number?
      instructions:
      - text: List my parcels with status {parcel_status}.
        slots:
          parcel_status: query.parcel_status
      - text: Find parcels for order number {order_number}.
        slots:
          order_number: query.order_number
      - text: List parcels updated after {updated_after}.
        slots:
          updated_after: query.updated_after
      method: generated
      generated: '2026-10-01'
- target: $.paths['/parcels'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an unannounced parcel
      effect: write
      questions:
      - Can I change a parcel's data before it's announced to the carrier?
      - How do I request a label for a parcel I created earlier without one?
      instructions:
      - text: Update the unannounced parcel with {parcel}.
        slots:
          parcel: requestBody.parcel
      - text: Request a label for the existing parcel {parcel}.
        slots:
          parcel: requestBody.parcel
      method: generated
      generated: '2026-10-01'
- target: $.paths['/parcels'].post
  update:
    x-apievangelist-phrasing:
      intent: Create one or more parcels
      effect: write
      questions:
      - How do I create a new parcel and announce it to the carrier right away?
      - Can I create several parcels in one request for later announcement?
      instructions:
      - text: Create a new parcel and announce it.
      - text: Create these parcels without announcing them yet.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/parcels/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a parcel
      effect: read
      questions:
      - How do I look up a single parcel by its ID?
      - What's the current status and tracking number of a given parcel?
      instructions:
      - text: Show parcel {id}.
        slots:
          id: path.id
      - text: Get the details of parcel {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/parcels/{id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel or delete a parcel
      effect: destructive
      questions:
      - Can I cancel a parcel after it has been announced?
      - What happens when I cancel a parcel that was never announced?
      instructions:
      - text: Cancel parcel {id}.
        slots:
          id: path.id
      - text: Cancel the label for parcel {id} with the carrier.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/parcels/{id}/return_portal_url'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the return portal link for a parcel
      effect: read
      questions:
      - Which branded return portal is linked to a parcel?
      - How do I give a customer the return portal URL for their parcel?
      instructions:
      - text: Get the return portal URL for parcel {id}.
        slots:
          id: path.id
      - text: Show which return portal parcel {id} uses.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'