# 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'