# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Thehiveryiq Com Arb Alloc API
  version: 1.0.0
extends: openapi/thehiveryiq-com-arb-alloc-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: 4
- target: $.paths['/v1/arb/alloc/scan'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview recommended slot reallocations
      effect: read
      questions:
      - Which model variants should get more or less traffic based on current performance?
      - Can I see recommended slot-share changes without applying them?
      instructions:
      - text: Scan variant performance and show recommended slot shares.
      - text: Preview the allocation proposals for every brood with live variants.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/arb/alloc/apply'].post
  update:
    x-apievangelist-phrasing:
      intent: Apply a slot reallocation
      effect: write
      questions:
      - How do I commit a slot reallocation rather than just preview it?
      - Does applying a reallocation actually change live traffic yet?
      instructions:
      - text: Apply the slot reallocation with dry run set to {dry_run}.
        slots:
          dry_run: query.dry_run
      - text: Persist the current reallocation proposals to history.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/arb/alloc/history'].get
  update:
    x-apievangelist-phrasing:
      intent: List past slot reallocation events
      effect: read
      questions:
      - What reallocations have been applied in the past?
      - Can I see the reallocation history for one brood?
      instructions:
      - text: Show the slot reallocation history.
      - text: List the last {limit} reallocations for brood {parent_id}.
        slots:
          limit: query.limit
          parent_id: query.parent_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/arb/alloc/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Estimate uplift from slot reallocations
      effect: read
      questions:
      - How much revenue uplift are the reallocations projected to produce?
      - Can I set the lookback window for the reallocation uplift estimate?
      instructions:
      - text: Get projected uplift from slot reallocations.
      - text: Compute reallocation uplift over the last {lookback_hours} hours.
        slots:
          lookback_hours: query.lookback_hours
      method: generated
      generated: '2026-09-26'