API Evangelist conversational phrasing for COS registration server Devices API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for COS registration server Devices API
  version: 1.0.0
extends: openapi/canonical-devices-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: 9
- target: $.paths['/api/v1/devices/'].get
  update:
    x-apievangelist-phrasing:
      intent: List registered devices
      effect: read
      questions:
      - Which devices are registered right now?
      - Can I list devices but return only certain fields?
      instructions:
      - text: List all registered devices.
      - text: List devices showing only fields {fields}.
        slots:
          fields: query.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/devices/'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a new device
      effect: write
      questions:
      - How do I register a new device with its address and certificate?
      - Can I attach Grafana dashboards when registering a device?
      instructions:
      - text: Register device {uid} at address {address} with certificate {certificate}, created {creation_date}.
        slots:
          uid: requestBody.uid
          address: requestBody.address
          certificate: requestBody.certificate
          creation_date: requestBody.creation_date
      - text: Register device {uid} with SSH key {public_ssh_key}.
        slots:
          uid: requestBody.uid
          public_ssh_key: requestBody.public_ssh_key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/devices/{uid}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a device by ID
      effect: read
      questions:
      - How do I look up everything stored about one device?
      - What address and dashboards are recorded for a device?
      instructions:
      - text: Show device {uid}.
        slots:
          uid: path.uid
      - text: Get all fields recorded for device {uid}.
        slots:
          uid: path.uid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/devices/{uid}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace all of a device's fields
      effect: write
      questions:
      - Can I overwrite every field of a registered device at once?
      - How do I fully replace a device record including its certificate?
      instructions:
      - text: Replace device {uid} with address {address} and certificate {certificate}.
        slots:
          uid: path.uid
          address: requestBody.address
          certificate: requestBody.certificate
      - text: Fully rewrite device {uid}'s record.
        slots:
          uid: path.uid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/devices/{uid}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a registered device
      effect: destructive
      questions:
      - How do I unregister a device?
      - Can I remove a device I decommissioned?
      instructions:
      - text: Delete device {uid}.
        slots:
          uid: path.uid
      - text: Unregister the decommissioned device {uid}.
        slots:
          uid: path.uid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/devices/{uid}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change some fields of a device
      effect: write
      questions:
      - Can I change only a device's address?
      - How do I update the alert rule files on one device without touching the rest?
      instructions:
      - text: Change device {uid}'s address to {address}.
        slots:
          uid: path.uid
          address: requestBody.address
      - text: Set Prometheus alert rule files {prometheus_alert_rule_files} on device {uid}.
        slots:
          prometheus_alert_rule_files: requestBody.prometheus_alert_rule_files
          uid: path.uid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/devices/{uid}/certificate/'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a device's certificate signing status
      effect: read
      questions:
      - Has my device's certificate request been signed yet?
      - Where do I get the signed certificate for a device?
      instructions:
      - text: Check the certificate signing status of device {uid}.
        slots:
          uid: path.uid
      - text: Fetch the signed certificate for device {uid} if it is ready.
        slots:
          uid: path.uid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/devices/{uid}/certificate/'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a certificate signing request
      effect: write
      questions:
      - How do I submit a CSR for a device?
      - What status does a newly submitted device CSR get?
      instructions:
      - text: Submit CSR {csr} for device {uid}.
        slots:
          csr: requestBody.csr
          uid: path.uid
      - text: File a certificate signing request {csr} for device {uid} dated {created_at}.
        slots:
          csr: requestBody.csr
          uid: path.uid
          created_at: requestBody.created_at
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/devices/{uid}/certificate/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Record a signed certificate for a device
      effect: write
      questions:
      - How does the charm mark a device certificate as signed?
      - Can I attach the CA chain once a device certificate is issued?
      instructions:
      - text: Set device {uid}'s certificate status to {status}.
        slots:
          uid: path.uid
          status: requestBody.status
      - text: Store signed certificate {certificate} with chain {chain} for device {uid}.
        slots:
          certificate: requestBody.certificate
          chain: requestBody.chain
          uid: path.uid
      method: generated
      generated: '2026-09-26'