# 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 A2a API
  version: 1.0.0
extends: openapi/thehiveryiq-com-a2a-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: 10
- target: $.paths['/.well-known/agent-card.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch the well-known A2A agent card catalog
      effect: read
      questions:
      - Where is the well-known agent-card.json that A2A registries crawl?
      - What does the top-level A2A v0.2 catalog of Hive agents contain?
      instructions:
      - text: Fetch the well-known agent-card.json catalog.
      - text: Read the top-level A2A discovery document at the well-known URL.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/.well-known/agents/{agent_id}/card.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch one agent's well-known A2A card
      effect: read
      questions:
      - What is the well-known card.json URL for a single agent?
      - Does a well-known per-agent card return 404 for unregistered agents?
      instructions:
      - text: Fetch the well-known card.json for agent {agent_id}.
        slots:
          agent_id: path.agent_id
      - text: Read agent {agent_id}'s card from its .well-known path.
        slots:
          agent_id: path.agent_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/a2a/cards'].get
  update:
    x-apievangelist-phrasing:
      intent: List published A2A agent cards
      effect: read
      questions:
      - Which A2A agent cards does Hive publish under the v1 cards endpoint?
      - Is listing A2A cards free?
      instructions:
      - text: List all published A2A cards from the v1 cards endpoint.
      - text: Get the A2A cards list.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/a2a/cards/{agent_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one A2A agent card from the cards endpoint
      effect: read
      questions:
      - Can I get a single agent's card through the v1 cards path?
      - What skills does a given agent advertise in its A2A card?
      instructions:
      - text: Get the A2A card for {agent_id} from the cards endpoint.
        slots:
          agent_id: path.agent_id
      - text: Show card {agent_id} via v1 cards.
        slots:
          agent_id: path.agent_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/a2a/harness:run-loop'].post
  update:
    x-apievangelist-phrasing:
      intent: Run the internal HARNESS agent loop
      effect: write
      questions:
      - Can I run the full discovery, quote, emit, verify and stats loop as a self-test?
      - Does harness traffic count toward paid calls or revenue?
      instructions:
      - text: Run the HARNESS internal agent loop and return the five-step report.
      - text: Execute the internal discovery-to-stats harness loop.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/a2a/agents'].get
  update:
    x-apievangelist-phrasing:
      intent: List A2A agents via the agents path
      effect: read
      questions:
      - Is there a /v1/a2a/agents path for clients that expect it?
      - What agents come back from the agents alias listing?
      instructions:
      - text: List A2A agents from the /v1/a2a/agents path.
      - text: Get the agents alias listing.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/a2a/agents/{agent_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one A2A agent via the agents path
      effect: read
      questions:
      - Can I fetch a single agent under /v1/a2a/agents instead of the cards path?
      - Which agents-path URL returns one agent's card?
      instructions:
      - text: Get agent {agent_id} from the /v1/a2a/agents path.
        slots:
          agent_id: path.agent_id
      - text: Look up agent {agent_id} via the agents alias.
        slots:
          agent_id: path.agent_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/a2a/handshake'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the A2A handshake request schema
      effect: read
      questions:
      - What should an A2A handshake request body look like?
      - Where can I see the handshake schema before actually opening a session?
      instructions:
      - text: Show the A2A handshake schema hint.
      - text: Get the handshake request format without executing one.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/a2a/handshake'].post
  update:
    x-apievangelist-phrasing:
      intent: Open an A2A handshake session
      effect: write
      questions:
      - How does my agent establish an A2A v0.2 session and get a session id?
      - Can I negotiate protocol versions and capabilities during the handshake?
      instructions:
      - text: Initiate an A2A handshake as agent {agent_did}.
        slots:
          agent_did: requestBody.agent_did
      - text: Handshake as {agent_name} offering protocol versions {protocol_versions} and requesting {capabilities_requested}.
        slots:
          agent_name: requestBody.agent_name
          protocol_versions: requestBody.protocol_versions
          capabilities_requested: requestBody.capabilities_requested
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/attestation/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the attestation system status
      effect: read
      questions:
      - Are the passport, custody, cargo, warranty and sanctions attestation families available?
      - Is attestation key material loaded and what pricing tier applies?
      instructions:
      - text: Show the attestation system status.
      - text: Check which attestation families are available right now.
      method: generated
      generated: '2026-09-26'