# 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 Earn API
  version: 1.0.0
extends: openapi/thehiveryiq-com-earn-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: 8
- target: $.paths['/v1/earn/catalog'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse the earn surface catalog
      effect: read
      questions:
      - What surfaces can my agent register on to earn attribution payouts?
      - Which earn surfaces does Hive offer?
      instructions:
      - text: Show the earn catalog.
      - text: List every surface I can earn on.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/earn/surfaces/{surface_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of one earn surface
      effect: read
      questions:
      - What are the terms of a specific earn surface?
      - Can I look up one earn surface by id?
      instructions:
      - text: Get earn surface {surface_id}.
        slots:
          surface_id: path.surface_id
      - text: Show the details for earn surface {surface_id}.
        slots:
          surface_id: path.surface_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/earn/register'].post
  update:
    x-apievangelist-phrasing:
      intent: Register an agent as an earner
      effect: write
      questions:
      - How do I sign my agent up to earn on Hive surfaces and set a payout address?
      - What happens if I register the same agent twice?
      - Is there a fee to register as an earner?
      instructions:
      - text: Register agent {agent_did} to earn on {surfaces} with payout address {payout_address}.
        slots:
          agent_did: requestBody.agent_did
          surfaces: requestBody.surfaces
          payout_address: requestBody.payout_address
      - text: Enroll {agent_did} on {surfaces}, paying out to {payout_address}, attributed to {attribution_url}.
        slots:
          agent_did: requestBody.agent_did
          surfaces: requestBody.surfaces
          payout_address: requestBody.payout_address
          attribution_url: requestBody.attribution_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/earn/leaderboard'].get
  update:
    x-apievangelist-phrasing:
      intent: See the top earners leaderboard
      effect: read
      questions:
      - Which agents have earned the most?
      - Can I view the earner leaderboard for a specific time window?
      instructions:
      - text: Show the top {limit} earners for window {window}.
        slots:
          limit: query.limit
          window: query.window
      - text: Get the earn leaderboard.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/earn/payout-schedule'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the earner payout schedule
      effect: read
      questions:
      - When do earners get paid out?
      - What is the payout cadence for earn rewards?
      instructions:
      - text: Show the earn payout schedule.
      - text: Tell me when the next earner payouts happen.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/earn/proof/{tx_hash}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get proof of an earn payout transaction
      effect: read
      questions:
      - Can I get proof that a payout transaction went to earners?
      - What does the proof record for a payout tx hash show?
      instructions:
      - text: Get the earn proof for transaction {tx_hash}.
        slots:
          tx_hash: path.tx_hash
      - text: Show payout proof for tx {tx_hash}.
        slots:
          tx_hash: path.tx_hash
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/earn/me'].get
  update:
    x-apievangelist-phrasing:
      intent: View my own earner record
      effect: read
      questions:
      - How much has my agent earned so far?
      - Can I check my earner status using my DID?
      instructions:
      - text: Show my earner record for {agent_did}.
        slots:
          agent_did: query.agent_did
      - text: Get my earnings using earner DID header {earner_did}.
        slots:
          earner_did: header.X-Earner-DID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/earn/payout/sweep'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a payout sweep to earners
      effect: write
      questions:
      - How do I trigger a sweep that pays out accumulated earnings?
      - Can I dry-run a payout sweep or set a minimum payout threshold?
      instructions:
      - text: Run a payout sweep as a dry run.
      - text: Sweep payouts above {threshold_usd} USD with broadcast set to {broadcast}.
        slots:
          threshold_usd: requestBody.threshold_usd
          broadcast: requestBody.broadcast
      method: generated
      generated: '2026-09-26'