API Evangelist conversational phrasing for Sendcloud Shipments API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Sendcloud Shipments API
  version: 1.0.0
extends: openapi/sendcloud-shipments-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: 12
- target: $.paths['/shipments/announce'].post
  update:
    x-apievangelist-phrasing:
      intent: Create and announce a shipment synchronously
      effect: write
      questions:
      - How do I create a shipment and get the label in the same response?
      - Can I announce a shipment and wait for the carrier to confirm?
      instructions:
      - text: Announce shipment of parcels {parcels} and wait for the label.
        slots:
          parcels: requestBody.parcels
      - text: Create a shipment now and return the carrier response.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments'].get
  update:
    x-apievangelist-phrasing:
      intent: List shipments
      effect: read
      questions:
      - Which shipments have I created or imported recently?
      - Can I filter shipments by tracking number or order number?
      - What shipments were announced before a certain date?
      instructions:
      - text: List shipments with status {parcel_status}.
        slots:
          parcel_status: query.parcel_status
      - text: Find the shipment with tracking number {tracking_number}.
        slots:
          tracking_number: query.tracking_number
      - text: List shipments announced after {announced_after}.
        slots:
          announced_after: query.announced_after
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create and announce a shipment asynchronously
      effect: write
      questions:
      - Can I submit a shipment and have it announced in the background?
      - What's the non-blocking way to announce a shipment?
      instructions:
      - text: Submit parcels {parcels} as a shipment announced in the background.
        slots:
          parcels: requestBody.parcels
      - text: Queue a new shipment for asynchronous announcement.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments/announce-with-shipping-rules'].post
  update:
    x-apievangelist-phrasing:
      intent: Announce a shipment with shipping rules, synchronously
      effect: write
      questions:
      - Can my shipping rules pick the method when I announce a shipment and wait for it?
      - How do I apply my shipping defaults and get the label back immediately?
      instructions:
      - text: Announce parcels {parcels} now applying shipping rules {apply_shipping_rules}.
        slots:
          parcels: requestBody.parcels
          apply_shipping_rules: requestBody.apply_shipping_rules
      - text: Create a shipment with my shipping defaults {apply_shipping_defaults} and wait for the label.
        slots:
          apply_shipping_defaults: requestBody.apply_shipping_defaults
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments/create-with-shipping-rules'].post
  update:
    x-apievangelist-phrasing:
      intent: Announce a shipment with shipping rules, asynchronously
      effect: write
      questions:
      - Can shipping rules and defaults be applied to a shipment announced in the background?
      - Is there an async version of creating shipments with my shipping rules?
      instructions:
      - text: Queue parcels {parcels} for background announcement with shipping rules {apply_shipping_rules}.
        slots:
          parcels: requestBody.parcels
          apply_shipping_rules: requestBody.apply_shipping_rules
      - text: Create an async shipment using shipping defaults {apply_shipping_defaults}.
        slots:
          apply_shipping_defaults: requestBody.apply_shipping_defaults
      method: generated
      generated: '2026-10-01'
- target: $.paths['/addresses/validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate a shipping address
      effect: read
      questions:
      - Can I check that a shipping address is valid before I create a label?
      - Which carrier do I need to name when checking an address for deliverability?
      instructions:
      - text: Validate the address {address} for carrier {carrier_code}.
        slots:
          address: requestBody.address
          carrier_code: requestBody.carrier_code
      - text: Check whether {address} is a deliverable address before shipping with {carrier_code}.
        slots:
          address: requestBody.address
          carrier_code: requestBody.carrier_code
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a shipment
      effect: read
      questions:
      - How do I look up one shipment by its ID?
      - What parcels and status does a particular shipment have?
      instructions:
      - text: Show shipment {id}.
        slots:
          id: path.id
      - text: Get the details of shipment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments/{id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel an announced shipment
      effect: destructive
      questions:
      - Can I cancel a shipment that's already been announced to the carrier?
      - Does every carrier allow announced shipments to be cancelled?
      instructions:
      - text: Cancel shipment {id}.
        slots:
          id: path.id
      - text: Cancel announced shipment {id} with the carrier.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shipments/{id}/return-portal-url'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the return portal link for a shipment
      effect: read
      questions:
      - How do I get a return portal link to send with a shipment?
      - Which return portal URL belongs to a given shipment?
      instructions:
      - text: Get the return portal URL for shipment {id}.
        slots:
          id: path.id
      - text: Show the return portal link of shipment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/integrations/{id}/shipments'].get
  update:
    x-apievangelist-phrasing:
      intent: List orders imported from a shop integration
      effect: read
      questions:
      - Which orders were imported from one of my webshop integrations?
      - Can I filter a shop's imported orders by date range or order number?
      instructions:
      - text: List imported orders for integration {id}.
        slots:
          id: path.id
      - text: Show orders imported into integration {id} between {start_date} and {end_date}.
        slots:
          id: path.id
          start_date: query.start_date
          end_date: query.end_date
      method: generated
      generated: '2026-10-01'
- target: $.paths['/integrations/{id}/shipments'].post
  update:
    x-apievangelist-phrasing:
      intent: Push orders into a shop integration
      effect: write
      questions:
      - How do I insert orders from my shop system into an API integration?
      - Can I update orders I already pushed to an integration?
      instructions:
      - text: Insert a list of orders into integration {id}.
        slots:
          id: path.id
      - text: Create or update shop orders in integration {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/integrations/{id}/shipments/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete an order from a shop integration
      effect: destructive
      questions:
      - How do I remove an order from Sendcloud after it was cancelled in my shop?
      - Can I delete an imported shop order from an integration?
      instructions:
      - text: Delete a shop order from integration {id}.
        slots:
          id: path.id
      - text: Remove the cancelled order from integration {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'