# 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 Fleet API
  version: 1.0.0
extends: openapi/thehiveryiq-com-fleet-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: 12
- target: $.paths['/v1/fleet/trawler/launch'].post
  update:
    x-apievangelist-phrasing:
      intent: Launch a new Trawler agent
      effect: write
      questions:
      - How do I launch a Trawler agent for my operator DID?
      - Can a new Trawler automatically cast nets and drop pots from its config?
      - What does the Trawler card report back after launch?
      instructions:
      - text: Launch a Trawler for operator {operator_did}.
        slots:
          operator_did: requestBody.operator_did
      - text: Launch a Trawler labelled {label} for {operator_did} using config {config}.
        slots:
          label: requestBody.label
          operator_did: requestBody.operator_did
          config: requestBody.config
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/fleet/trawler/{trawler_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Inspect a Trawler
      effect: read
      questions:
      - How many agents has a specific Trawler caught so far?
      - Where can I see one Trawler's net and pot counts?
      instructions:
      - text: Show Trawler {trawler_id}.
        slots:
          trawler_id: path.trawler_id
      - text: Get the catch and net counts for Trawler {trawler_id}.
        slots:
          trawler_id: path.trawler_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/fleet/net/cast'].post
  update:
    x-apievangelist-phrasing:
      intent: Cast a net over a region of agent space
      effect: write
      questions:
      - How do I cast a wide net to attract agents in a region like a GitHub topic?
      - Can I set a net's lifetime, reach and viscosity?
      instructions:
      - text: Cast a net from Trawler {trawler_id} over {region} with attractant {attractant}.
        slots:
          trawler_id: requestBody.trawler_id
          region: requestBody.region
          attractant: requestBody.attractant
      - text: Cast a net over {region} for Trawler {trawler_id}, offering {attractant}, lasting {ttl_sec} seconds.
        slots:
          region: requestBody.region
          trawler_id: requestBody.trawler_id
          attractant: requestBody.attractant
          ttl_sec: requestBody.ttl_sec
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/fleet/net/{net_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Inspect a cast net
      effect: read
      questions:
      - How can I check the details of a net I already cast?
      - Is a particular net still active or has it expired?
      instructions:
      - text: Show net {net_id}.
        slots:
          net_id: path.net_id
      - text: Look up the region and TTL of net {net_id}.
        slots:
          net_id: path.net_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/fleet/net/expire'].post
  update:
    x-apievangelist-phrasing:
      intent: Expire all nets past their TTL
      effect: destructive
      questions:
      - Is there a cron-friendly call to expire every net that has outlived its TTL?
      - How many stale nets get cleaned up when I run expiry?
      instructions:
      - text: Expire all nets that are past their TTL.
      - text: Run the net expiry sweep and tell me how many were updated.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/fleet/pot/drop'].post
  update:
    x-apievangelist-phrasing:
      intent: Drop a crab pot at a fixed location
      effect: write
      questions:
      - How do I drop a persistent crab pot at a registry location to attract agents?
      - Can a pot carry a USDC reward signal for agents who step aboard?
      instructions:
      - text: Drop a pot from Trawler {trawler_id} at {location} baited with {bait_description}.
        slots:
          trawler_id: requestBody.trawler_id
          location: requestBody.location
          bait_description: requestBody.bait_description
      - text: Drop a crab pot at {location} for {trawler_id} offering {economic_payload_usdc} USDC, bait {bait_description}.
        slots:
          location: requestBody.location
          trawler_id: requestBody.trawler_id
          economic_payload_usdc: requestBody.economic_payload_usdc
          bait_description: requestBody.bait_description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/fleet/pot/{pot_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Inspect a crab pot
      effect: read
      questions:
      - What's the current state of a crab pot I dropped?
      - How do I see the bait and location of one pot?
      instructions:
      - text: Show crab pot {pot_id}.
        slots:
          pot_id: path.pot_id
      - text: Get the details of pot {pot_id}.
        slots:
          pot_id: path.pot_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/fleet/haul'].get
  update:
    x-apievangelist-phrasing:
      intent: List recent catches in the haul
      effect: read
      questions:
      - Which agents have been caught most recently?
      - Can I list more than the default 50 haul rows?
      instructions:
      - text: List the latest catches in the haul.
      - text: Show the {limit} most recent haul records.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/fleet/haul/{haul_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Inspect a haul record
      effect: read
      questions:
      - How do I look up a single catch record by its haul ID?
      - Where was a specific caught agent routed?
      instructions:
      - text: Show haul record {haul_id}.
        slots:
          haul_id: path.haul_id
      - text: Tell me where haul {haul_id} was routed.
        slots:
          haul_id: path.haul_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/fleet/mothership/intake'].post
  update:
    x-apievangelist-phrasing:
      intent: Land an agent at the Mothership
      effect: write
      questions:
      - How does an arriving agent opt in and get routed to the right supermodel?
      - What gates does Mothership intake check before routing an agent?
      - Does intake create a haul record and open affordances for the agent?
      instructions:
      - text: Run Mothership intake for agent {agent_did} with need {need} and consent {consent}.
        slots:
          agent_did: requestBody.agent_did
          need: requestBody.need
          consent: requestBody.consent
      - text: Land agent {agent_did} from Trawler {trawler_id}, need {need}, with a {tip_usdc} USDC tip.
        slots:
          agent_did: requestBody.agent_did
          trawler_id: requestBody.trawler_id
          need: requestBody.need
          tip_usdc: requestBody.tip_usdc
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/fleet/mothership/route'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up the best supermodel for a need
      effect: read
      questions:
      - Which supermodel would a given need be routed to, without logging a catch?
      - Can I preview routing for a need string?
      instructions:
      - text: Find the supermodel that should handle the need {need}.
        slots:
          need: query.need
      - text: Preview the route for need {need} without creating a haul record.
        slots:
          need: query.need
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/fleet/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get fleet-level catch and revenue stats
      effect: read
      questions:
      - What's the fleet's conversion rate from catches to routed agents?
      - How many nets and pots are active across the fleet?
      instructions:
      - text: Show fleet stats.
      - text: Give me agents caught, revenue by supermodel and active nets for the fleet.
      method: generated
      generated: '2026-09-26'