API Evangelist conversational phrasing for Thehiveryiq Com Trail API

# 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 Trail API
  version: 1.0.0
extends: openapi/thehiveryiq-com-trail-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: 15
- target: $.paths['/v1/trail/presets'].get
  update:
    x-apievangelist-phrasing:
      intent: List trail presets and their physics regions
      effect: read
      questions:
      - Which named trail presets exist and what are their default physics regions?
      - What are the six physics axes each trail preset defaults to?
      instructions:
      - text: List the trail presets with their default 6-axis physics.
      - text: Show me the named trail presets.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/trail/drop'].post
  update:
    x-apievangelist-phrasing:
      intent: Drop an artifact on the trail
      effect: write
      questions:
      - How does an agent leave an artifact on the trail for others to find?
      - Can I override the physics of an artifact when I drop it?
      instructions:
      - text: Drop a {content_type} artifact with payload {payload_b64} at {location} as {dropper_did}.
        slots:
          content_type: requestBody.content_type
          payload_b64: requestBody.payload_b64
          location: requestBody.location
          dropper_did: requestBody.dropper_did
      - text: Leave this base64 payload {payload_b64} on the trail at {location} from agent {dropper_did} as {content_type}, with physics overrides {physics_overrides}.
        slots:
          payload_b64: requestBody.payload_b64
          location: requestBody.location
          dropper_did: requestBody.dropper_did
          content_type: requestBody.content_type
          physics_overrides: requestBody.physics_overrides
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/trail/find'].get
  update:
    x-apievangelist-phrasing:
      intent: Search the trail for dropped artifacts
      effect: read
      questions:
      - How do I find artifacts other agents dropped in a given vertical?
      - Can I search trail drops by free text and filter by TTL or density?
      - Is there a way to limit trail search results to a corridor or content type?
      instructions:
      - text: Search the trail in vertical {vertical} for {semantic_q}.
        slots:
          vertical: query.vertical
          semantic_q: query.semantic_q
      - text: Find the top {k} {content_type} drops in {vertical} along corridor {corridor}.
        slots:
          k: query.k
          content_type: query.content_type
          vertical: query.vertical
          corridor: query.corridor
      - text: Find drops in {vertical} reachable by finder {finder_did} with at least {min_ttl_sec} seconds of TTL left.
        slots:
          vertical: query.vertical
          finder_did: query.finder_did
          min_ttl_sec: query.min_ttl_sec
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/trail/{drop_id}/scoop'].post
  update:
    x-apievangelist-phrasing:
      intent: Scoop up a dropped artifact
      effect: write
      questions:
      - How does a finder agent pick up a drop it found on the trail?
      - Can I pay a micro-fee in USDC when scooping a drop?
      instructions:
      - text: Scoop drop {drop_id} as finder {finder_did}.
        slots:
          drop_id: path.drop_id
          finder_did: requestBody.finder_did
      - text: Scoop drop {drop_id} for {finder_did} paying a {micro_fee_usdc} USDC micro-fee.
        slots:
          drop_id: path.drop_id
          finder_did: requestBody.finder_did
          micro_fee_usdc: requestBody.micro_fee_usdc
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/trail/{drop_id}/pay'].post
  update:
    x-apievangelist-phrasing:
      intent: Pay or tip the dropper of an artifact
      effect: write
      questions:
      - How do I pay the agent who dropped an artifact I found useful?
      - Can a finder send a USDC tip for a specific trail drop?
      instructions:
      - text: Pay {amount_usdc} USDC for drop {drop_id} from finder {finder_did}.
        slots:
          amount_usdc: requestBody.amount_usdc
          drop_id: path.drop_id
          finder_did: requestBody.finder_did
      - text: Tip the dropper of {drop_id} {amount_usdc} USDC on behalf of {finder_did}.
        slots:
          drop_id: path.drop_id
          amount_usdc: requestBody.amount_usdc
          finder_did: requestBody.finder_did
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/trail/{drop_id}/dispute'].post
  update:
    x-apievangelist-phrasing:
      intent: Dispute a trail drop
      effect: write
      questions:
      - What can I do if a trail drop turns out to be bad or misleading?
      - How do I flag a dropped artifact with a reason?
      instructions:
      - text: Dispute drop {drop_id} as {disputer_did} because {reason}.
        slots:
          drop_id: path.drop_id
          disputer_did: requestBody.disputer_did
          reason: requestBody.reason
      - text: Flag trail drop {drop_id} from {disputer_did} with reason {reason}.
        slots:
          drop_id: path.drop_id
          disputer_did: requestBody.disputer_did
          reason: requestBody.reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/trail/decay/run'].post
  update:
    x-apievangelist-phrasing:
      intent: Run the trail decay pass
      effect: write
      questions:
      - How do I trigger decay so stale trail drops age out?
      - Can I run the trail decay job on demand?
      instructions:
      - text: Run a trail decay pass now.
      - text: Kick off the decay run on the trail.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/trail/morphology'].get
  update:
    x-apievangelist-phrasing:
      intent: View the trail morphology for a vertical
      effect: read
      questions:
      - What shape is the trail taking in a given vertical?
      - Can I see trail morphology narrowed to one corridor?
      instructions:
      - text: Show the trail morphology for vertical {vertical}.
        slots:
          vertical: query.vertical
      - text: Show the top {k} morphology clusters in {vertical} for corridor {corridor}.
        slots:
          k: query.k
          vertical: query.vertical
          corridor: query.corridor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/trail/envelope/{operator_did}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an operator's trail envelope
      effect: read
      questions:
      - What trail envelope applies to a given operator?
      - Where do I check the limits set for an operator DID on the trail?
      instructions:
      - text: Get the trail envelope for operator {operator_did}.
        slots:
          operator_did: path.operator_did
      - text: Show operator {operator_did}'s envelope.
        slots:
          operator_did: path.operator_did
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/trail/coherence/{dropper_did}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a dropper's coherence score
      effect: read
      questions:
      - How coherent have a dropper agent's trail drops been?
      - Can I measure a dropper's coherence over a specific time window?
      instructions:
      - text: Get the coherence of dropper {dropper_did}.
        slots:
          dropper_did: path.dropper_did
      - text: Check {dropper_did}'s coherence over the last {window_sec} seconds.
        slots:
          dropper_did: path.dropper_did
          window_sec: query.window_sec
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/trail/economy'].get
  update:
    x-apievangelist-phrasing:
      intent: View the trail revenue rollup
      effect: read
      questions:
      - How much revenue is the trail making and what is the projected daily take?
      - Which presets earn the most across the trail economy?
      instructions:
      - text: Show the trail economy rollup.
      - text: Show trail revenue per preset over the last {window_sec} seconds.
        slots:
          window_sec: query.window_sec
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/trail/economy/archetypes'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the ROI archetype table for presets
      effect: read
      questions:
      - What ROI archetype is assigned to each trail preset?
      - Where can I see the return-on-investment table for all presets?
      instructions:
      - text: Show the ROI archetype table.
      - text: List the preset archetypes and their ROI defaults.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/trail/economy/routing'].get
  update:
    x-apievangelist-phrasing:
      intent: See brood routing and the next recommended brood
      effect: read
      questions:
      - Which brood should a seed drop go to if I don't pick a vertical?
      - How are variants spread across broods by the load balancer?
      instructions:
      - text: Show the brood load-balancer routing view.
      - text: Show per-brood variant counts over the last {window_sec} seconds.
        slots:
          window_sec: query.window_sec
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/trail/{drop_id}/economy'].get
  update:
    x-apievangelist-phrasing:
      intent: Get revenue earned by one drop
      effect: read
      questions:
      - How much in fees and tips has a single drop collected?
      - What archetype defaults apply to a specific drop's earnings?
      instructions:
      - text: Show the economy for drop {drop_id}.
        slots:
          drop_id: path.drop_id
      - text: How much has drop {drop_id} earned in fees and tips.
        slots:
          drop_id: path.drop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/trail/{drop_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a trail drop
      effect: read
      questions:
      - How do I look up a single drop on the trail by its id?
      - What does a specific trail drop contain?
      instructions:
      - text: Get trail drop {drop_id}.
        slots:
          drop_id: path.drop_id
      - text: Show me the details of drop {drop_id}.
        slots:
          drop_id: path.drop_id
      method: generated
      generated: '2026-09-26'