# 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 R3 Delegation API
  version: 1.0.0
extends: openapi/thehiveryiq-com-r3-delegation-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/delegation/issue'].post
  update:
    x-apievangelist-phrasing:
      intent: Issue a delegation envelope signed by Hive
      effect: write
      questions:
      - How do I give my agent a signed delegation limiting what it may do and spend?
      - Can I cap an agent's USDC spend and restrict its endpoints in a delegation?
      - What if I don't have my own operator keypair to sign a delegation?
      instructions:
      - text: Issue a delegation envelope for agent {agent_id}.
        slots:
          agent_id: requestBody.agent_id
      - text: Delegate to {agent_id} the actions {allowed_actions} with a spend cap of {max_spend_usdc} USDC for {ttl_seconds} seconds.
        slots:
          agent_id: requestBody.agent_id
          allowed_actions: requestBody.allowed_actions
          max_spend_usdc: requestBody.max_spend_usdc
          ttl_seconds: requestBody.ttl_seconds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/delegation/operator-sign'].post
  update:
    x-apievangelist-phrasing:
      intent: Counter-stamp an envelope I signed myself
      effect: write
      questions:
      - How do I submit a delegation I signed with my own operator Ed25519 key?
      - Will Hive counter-stamp and store an operator-signed envelope?
      instructions:
      - text: Counter-stamp envelope {envelope} signed with {operator_signature} by key {operator_pubkey}.
        slots:
          envelope: requestBody.envelope
          operator_signature: requestBody.operator_signature
          operator_pubkey: requestBody.operator_pubkey
      - text: Submit my operator-signed delegation {envelope} (signature {operator_signature}, pubkey {operator_pubkey}) for issuer stamping.
        slots:
          envelope: requestBody.envelope
          operator_signature: requestBody.operator_signature
          operator_pubkey: requestBody.operator_pubkey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/delegation/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify a delegation envelope
      effect: read
      questions:
      - How do I check a delegation's signatures, expiry and revocation status?
      - Is verifying a delegation envelope free?
      instructions:
      - text: Verify delegation envelope {envelope}.
        slots:
          envelope: requestBody.envelope
      - text: Check whether {envelope} is still valid and unrevoked.
        slots:
          envelope: requestBody.envelope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/delegation/revoke/{jti}'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke a delegation
      effect: destructive
      questions:
      - How do I cancel a delegation I gave an agent?
      - What does verification return after a delegation is revoked?
      instructions:
      - text: Revoke delegation {jti}.
        slots:
          jti: path.jti
      - text: Cancel the agent's authority under delegation {jti}.
        slots:
          jti: path.jti
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/delegation/pubkey'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the delegation signing public keys
      effect: read
      questions:
      - Which public keys should I use to verify delegation signatures offline?
      - What is the soft-operator signer's public key?
      instructions:
      - text: Get the issuer and soft-operator public keys.
      - text: Fetch the delegation signing keys.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/delegation/{jti}'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch a stored delegation
      effect: read
      questions:
      - How do I look up a delegation I issued earlier by its ID?
      - Can I see the limits recorded in a stored delegation?
      instructions:
      - text: Get delegation {jti}.
        slots:
          jti: path.jti
      - text: Show me the stored envelope for {jti}.
        slots:
          jti: path.jti
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/firewall/evaluate'].post
  update:
    x-apievangelist-phrasing:
      intent: Evaluate a request against a delegation
      effect: read
      questions:
      - Would this agent request be allowed, blocked or sent for human approval under its delegation?
      - What decisions can the agent firewall return?
      instructions:
      - text: Evaluate request {request} against delegation envelope {envelope}.
        slots:
          request: requestBody.request
          envelope: requestBody.envelope
      - text: Get the firewall decision for envelope {envelope}.
        slots:
          envelope: requestBody.envelope
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/delegation/check'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify delegation and get firewall decision at once
      effect: read
      questions:
      - Can I verify a delegation and get the firewall decision in one call?
      - How do I find out what to fix when an agent's request is denied?
      instructions:
      - text: Check stored delegation {jti} against request {request} and suggest next steps.
        slots:
          jti: requestBody.jti
          request: requestBody.request
      - text: Run the combined verify-and-firewall check for envelope {envelope}.
        slots:
          envelope: requestBody.envelope
      method: generated
      generated: '2026-09-26'