# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for NATS HTTP Gateway KV API
  version: 1.0.0
extends: openapi/synadia-communications-kv-api-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: 4
- target: $.paths['/kv/{bucket}/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a value from a KV bucket
      effect: read
      questions:
      - How do I read the value stored under a key?
      - Can I fetch an older revision of a key's value?
      instructions:
      - text: Get the value of key {key} in bucket {bucket}.
        slots:
          key: path.key
          bucket: path.bucket
      - text: Read key {key} from bucket {bucket} at revision {revision}.
        slots:
          key: path.key
          bucket: path.bucket
          revision: query.revision
      method: generated
      generated: '2026-10-01'
- target: $.paths['/kv/{bucket}/{key}'].put
  update:
    x-apievangelist-phrasing:
      intent: Put a value in a KV bucket
      effect: write
      questions:
      - Can I write a key whether or not it already exists?
      - Is optimistic concurrency supported by passing the previous revision?
      instructions:
      - text: Put a value at key {key} in bucket {bucket}.
        slots:
          key: path.key
          bucket: path.bucket
      - text: Update key {key} in bucket {bucket} only if it's still at revision {previousRevision}.
        slots:
          key: path.key
          bucket: path.bucket
          previousRevision: query.previousRevision
      method: generated
      generated: '2026-10-01'
- target: $.paths['/kv/{bucket}/{key}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new key only if absent
      effect: write
      questions:
      - Can I add a key so the call fails if it already exists?
      - What's the safe way to create a key without overwriting?
      instructions:
      - text: Create key {key} in bucket {bucket} only if it doesn't exist.
        slots:
          key: path.key
          bucket: path.bucket
      - text: Add a brand-new entry {key} to bucket {bucket}.
        slots:
          key: path.key
          bucket: path.bucket
      method: generated
      generated: '2026-10-01'
- target: $.paths['/kv/{bucket}/{key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a key from a KV bucket
      effect: destructive
      questions:
      - Can I delete a key and also purge its history?
      - What's the way to remove an entry from a key-value bucket?
      instructions:
      - text: Delete key {key} from bucket {bucket}.
        slots:
          key: path.key
          bucket: path.bucket
      - text: Delete key {key} in bucket {bucket} and purge its history (purge={purge}).
        slots:
          key: path.key
          bucket: path.bucket
          purge: query.purge
      method: generated
      generated: '2026-10-01'