# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Drip Usage API
  version: 1.0.0
extends: openapi/drippay-usage-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: 6
- target: $.paths['/v1/usage'].get
  update:
    x-apievangelist-phrasing:
      intent: List recent usage events and charges
      effect: read
      questions:
      - What usage has been recorded recently, with the charges it created?
      - Can I see recent billable usage for just one customer?
      instructions:
      - text: List recent usage events.
      - text: Show the last {limit} usage events for customer {customerId}.
        slots:
          limit: query.limit
          customerId: query.customerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/usage'].post
  update:
    x-apievangelist-phrasing:
      intent: Record usage and charge immediately
      effect: write
      questions:
      - How do I bill a customer for usage and wait until the charge is settled on-chain?
      - Can I charge by my own external customer ID instead of the Drip ID?
      instructions:
      - text: Charge customer {customerId} for {quantity} {usageType} with key {idempotencyKey} and wait for settlement.
        slots:
          customerId: requestBody.customerId
          quantity: requestBody.quantity
          usageType: requestBody.usageType
          idempotencyKey: requestBody.idempotencyKey
      - text: Record settled usage of {quantity} for external customer {externalCustomerId}, key {idempotencyKey}.
        slots:
          quantity: requestBody.quantity
          externalCustomerId: requestBody.externalCustomerId
          idempotencyKey: requestBody.idempotencyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/usage/async'].post
  update:
    x-apievangelist-phrasing:
      intent: Record usage and charge in the background
      effect: write
      questions:
      - Can I record billable usage without waiting for the charge to settle?
      - How will I know whether a background usage charge succeeded or failed?
      instructions:
      - text: Record {quantity} {usageType} for {customerId} asynchronously with key {idempotencyKey}.
        slots:
          quantity: requestBody.quantity
          usageType: requestBody.usageType
          customerId: requestBody.customerId
          idempotencyKey: requestBody.idempotencyKey
      - text: Queue a background charge for customer {customerId}, idempotency key {idempotencyKey}.
        slots:
          customerId: requestBody.customerId
          idempotencyKey: requestBody.idempotencyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/usage/internal'].post
  update:
    x-apievangelist-phrasing:
      intent: Track usage without billing
      effect: write
      questions:
      - How do I track internal team usage without charging anyone?
      - Can I log a pilot customer's usage for visibility but not bill it?
      instructions:
      - text: Log {quantity} {usageType} for {customerId} as internal, non-billed usage, key {idempotencyKey}.
        slots:
          quantity: requestBody.quantity
          usageType: requestBody.usageType
          customerId: requestBody.customerId
          idempotencyKey: requestBody.idempotencyKey
      - text: Record one unbilled usage event with key {idempotencyKey}.
        slots:
          idempotencyKey: requestBody.idempotencyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/usage/internal/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Track unbilled usage at high throughput
      effect: write
      questions:
      - What should I use to send over a million unbilled usage events a day?
      - Is there a buffered, bulk-insert way to record internal usage?
      instructions:
      - text: Send internal usage {idempotencyKey} for {customerId} through the high-throughput buffer.
        slots:
          idempotencyKey: requestBody.idempotencyKey
          customerId: requestBody.customerId
      - text: Record unbilled {usageType} usage in batched mode with key {idempotencyKey}.
        slots:
          usageType: requestBody.usageType
          idempotencyKey: requestBody.idempotencyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/usage/quota'].get
  update:
    x-apievangelist-phrasing:
      intent: Check this month's event usage against plan quota
      effect: read
      questions:
      - Have I exceeded my monthly event quota on Drip?
      - When does my event quota reset, and what does overage cost per event?
      instructions:
      - text: Check my current-month event usage against my plan quota.
      - text: Tell me whether my event quota is exceeded and when it resets.
      method: generated
      generated: '2026-09-26'