# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Algovoi Co Uk Ap2 API
  version: 1.0.0
extends: openapi/algovoi-co-uk-ap2-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 7
- target: $.paths['/v1/ap2/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify a payer's AP2 mandate credential
      effect: read
      questions:
      - How do I check that an AP2 mandate a payer submitted carries a valid signed JWT?
      - Can I verify an AP2 mandate on behalf of a specific merchant?
      instructions:
      - text: Verify AP2 mandate {mandate}.
        slots:
          mandate: requestBody.mandate
      - text: Check the AP2 mandate {mandate} is valid for merchant {merchant_id}.
        slots:
          mandate: requestBody.mandate
          merchant_id: requestBody.merchant_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/ap2/intent'].post
  update:
    x-apievangelist-phrasing:
      intent: Open an AP2 shopping session with an IntentMandate
      effect: write
      questions:
      - How does an agent start an AP2 shopping session?
      - Is the user's SD-JWT authorization checked when the intent is submitted, or later at pay?
      instructions:
      - text: Submit IntentMandate {mandate} to open a shopping session.
        slots:
          mandate: requestBody.mandate
      - text: Start an AP2 session with intent {mandate} and user authorization {user_authorization}.
        slots:
          mandate: requestBody.mandate
          user_authorization: requestBody.user_authorization
      method: generated
      generated: '2026-10-01'
- target: $.paths['/ap2/cart'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a merchant-signed CartMandate
      effect: write
      questions:
      - How do I attach a merchant-signed cart to an accepted AP2 intent?
      - What is the CartMandate checked against when I submit it?
      instructions:
      - text: Submit CartMandate {mandate} against intent {intent_id}.
        slots:
          mandate: requestBody.mandate
          intent_id: requestBody.intent_id
      - text: Attach the merchant-signed cart {mandate} to AP2 intent {intent_id}.
        slots:
          mandate: requestBody.mandate
          intent_id: requestBody.intent_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/ap2/pay'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a PaymentMandate and get a crypto challenge
      effect: write
      questions:
      - How do I pay for an AP2 cart once it is accepted?
      - What does the gateway return after it verifies the PaymentMandate, a crypto challenge?
      instructions:
      - text: Submit PaymentMandate {mandate} for cart {cart_id}.
        slots:
          mandate: requestBody.mandate
          cart_id: requestBody.cart_id
      - text: Start payment on AP2 cart {cart_id} and return the crypto challenge.
        slots:
          cart_id: requestBody.cart_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/ap2/confirm'].post
  update:
    x-apievangelist-phrasing:
      intent: Confirm an AP2 on-chain payment and get a JWT
      effect: write
      questions:
      - After the on-chain transfer, how do I get the AP2 access token?
      - Which network and transaction details are needed to confirm an AP2 payment?
      instructions:
      - text: Confirm AP2 payment {payment_id} with transaction {tx_id} on {network}.
        slots:
          payment_id: requestBody.payment_id
          tx_id: requestBody.tx_id
          network: requestBody.network
      - text: Verify tx {tx_id} for payment {payment_id} and issue the JWT.
        slots:
          tx_id: requestBody.tx_id
          payment_id: requestBody.payment_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/ap2/status/{cart_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Inspect an AP2 mandate chain by cart
      effect: read
      questions:
      - Where is my AP2 cart in the intent, cart, payment and confirm chain?
      - Can I see the mandate chain state for one cart?
      instructions:
      - text: Show the AP2 mandate chain state for cart {cart_id}.
        slots:
          cart_id: path.cart_id
      - text: Check how far cart {cart_id} has progressed through AP2.
        slots:
          cart_id: path.cart_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/ap2/extensions'].get
  update:
    x-apievangelist-phrasing:
      intent: List the AP2 extensions this gateway supports
      effect: read
      questions:
      - Which AP2 extensions and crypto payment methods does the gateway support?
      - What should my agent discover before building a CartMandate?
      instructions:
      - text: List the supported AP2 extensions.
      - text: Show which crypto rails are available as AP2 payment methods.
      method: generated
      generated: '2026-10-01'