API Evangelist conversational phrasing for IBANforge API Keys API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for IBANforge API Keys API
  version: 1.0.0
extends: openapi/ibanforge-api-keys-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: 13
- target: $.paths['/v1/keys/generate'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate a free API key
      effect: write
      questions:
      - Can I get an API key with no email and no card?
      - What is the difference between an anonymous key and one issued to an email address?
      - Why did key creation answer verification_required and mail me a code?
      instructions:
      - text: Create an anonymous free API key.
      - text: Generate a free API key registered to {email}.
        slots:
          email: requestBody.email
      - text: Finish creating the key for {email} with verification code {code}.
        slots:
          email: requestBody.email
          code: requestBody.code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/keys/device'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a device authorization request for a key
      effect: write
      questions:
      - How can an agent get an API key approved by a human without handling their email?
      - How long does a device authorization request stay open?
      - What code and link do I show the human for device approval?
      instructions:
      - text: Open a device authorization request for an API key.
      - text: Start a device key request as {client_name}, explaining it is for {reason}.
        slots:
          client_name: requestBody.client_name
          reason: requestBody.reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/keys/device/token'].post
  update:
    x-apievangelist-phrasing:
      intent: Collect the key after device approval
      effect: write
      questions:
      - How often should an agent poll for the key after asking a human to approve it?
      - What does slow_down mean when waiting for a device-approved key?
      - Is the approved key handed over more than once?
      instructions:
      - text: Poll for the approved API key with device code {device_code}.
        slots:
          device_code: requestBody.device_code
      - text: Collect the key for device request {device_code} once the human approves it.
        slots:
          device_code: requestBody.device_code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/keys/device/lookup'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up a pending device request by its code
      effect: write
      questions:
      - What does a pending device request show before I approve it?
      - Where do I get the approval token needed to approve or refuse a device request?
      instructions:
      - text: Look up the pending device request for user code {user_code}.
        slots:
          user_code: requestBody.user_code
      - text: Fetch the approval token for device code {user_code} the human typed.
        slots:
          user_code: requestBody.user_code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/keys/device/approve'].post
  update:
    x-apievangelist-phrasing:
      intent: Approve a device request and issue the key
      effect: write
      questions:
      - Can I approve an agent's key request and raise it to 200 requests a month by verifying my mailbox?
      - What does approving a device request without an email give the agent?
      instructions:
      - text: Approve device request {user_code} with approval token {approval_token}.
        slots:
          user_code: requestBody.user_code
          approval_token: requestBody.approval_token
      - text: Approve device request {user_code} using token {approval_token} and verify mailbox {email}.
        slots:
          user_code: requestBody.user_code
          approval_token: requestBody.approval_token
          email: requestBody.email
      - text: Confirm mailbox {email} with code {code} to approve device request {user_code} (token {approval_token}).
        slots:
          user_code: requestBody.user_code
          approval_token: requestBody.approval_token
          email: requestBody.email
          code: requestBody.code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/keys/device/deny'].post
  update:
    x-apievangelist-phrasing:
      intent: Refuse a device key request
      effect: destructive
      questions:
      - What should I do with a device approval request that is not mine?
      - Can the agent try again after I refuse its key request?
      instructions:
      - text: Deny device request {user_code} with approval token {approval_token}.
        slots:
          user_code: requestBody.user_code
          approval_token: requestBody.approval_token
      - text: Refuse the key request for code {user_code}; the token is {approval_token}.
        slots:
          user_code: requestBody.user_code
          approval_token: requestBody.approval_token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/keys/usage'].get
  update:
    x-apievangelist-phrasing:
      intent: Check this month's usage of an API key
      effect: read
      questions:
      - How many requests do I have left on my API key this month?
      - Does my key's allowance reset monthly or is it a lifetime limit?
      - Which tier is my API key on?
      instructions:
      - text: Show the usage and remaining quota of my API key.
      - text: Tell me whether my key is anonymous, email, claimed or paid.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/keys/report'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the activity report of the presented key
      effect: read
      questions:
      - Which endpoints has my API key called, and what failed?
      - Can I tell if my API key was used from unusual networks?
      - Can the key report cover a full year of traffic?
      instructions:
      - text: Show the activity report for the API key I'm using.
      - text: Report what my key did over the last {days} days.
        slots:
          days: query.days
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/keys/revoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Permanently revoke the presented API key
      effect: destructive
      questions:
      - My API key leaked, how can I kill it immediately?
      - Is revoking a key reversible?
      instructions:
      - text: Revoke the API key I'm presenting, permanently.
      - text: Deactivate this leaked key without issuing a replacement.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/keys/claim'].post
  update:
    x-apievangelist-phrasing:
      intent: Upgrade an anonymous key to the free tier
      effect: write
      questions:
      - Can I raise my anonymous key from 25 to 200 requests a month without changing the key?
      - Why does claiming my key answer unused_key?
      instructions:
      - text: Claim my anonymous key by verifying mailbox {email}.
        slots:
          email: requestBody.email
      - text: Complete the claim of my key for {email} with code {code}.
        slots:
          email: requestBody.email
          code: requestBody.code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/keys/rotate'].post
  update:
    x-apievangelist-phrasing:
      intent: Rotate an API key into a fresh one
      effect: destructive
      questions:
      - Can I swap my API key for a new one and keep my plan and credits?
      - Does rotating a key reset my monthly quota?
      instructions:
      - text: Rotate my current API key and give me the replacement.
      - text: Replace this key with a fresh one and revoke the old one.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get detailed usage statistics by operation
      effect: read
      questions:
      - What are the API's usage and revenue figures broken down by operation type?
      - Which operation types get the most calls right now?
      instructions:
      - text: Show the detailed API statistics by operation type.
      - text: Get the current usage and revenue breakdown.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stats/history'].get
  update:
    x-apievangelist-phrasing:
      intent: Get per-day statistics for a period
      effect: read
      questions:
      - What did daily API usage look like over the past week?
      - How far back can the per-day statistics go?
      instructions:
      - text: Show per-day statistics for the last {period} days.
        slots:
          period: query.period
      - text: Get the daily usage history for the default seven days.
      method: generated
      generated: '2026-09-26'