API Evangelist conversational phrasing for Mandateshield Com Execution evidence API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Mandateshield Com Execution evidence API
  version: 1.0.0
extends: openapi/mandateshield-com-execution-evidence-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: 5
- target: $.paths['/api/v2/execution-permits/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify a signed execution permit
      effect: read
      questions:
      - How do I check that a provider-bound execution permit's signature and structure are valid?
      - Does verifying a permit tell me whether it was already redeemed or revoked?
      - Can I confirm a permit was issued for my exact audience before using it?
      instructions:
      - text: Verify execution permit {compact}.
        slots:
          compact: requestBody.compact
      - text: Check permit {compact} cryptographically and confirm its audience is exactly {expected_audience}.
        slots:
          compact: requestBody.compact
          expected_audience: requestBody.expected_audience
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/execution-permits/redeem'].post
  update:
    x-apievangelist-phrasing:
      intent: Claim an execution permit before provider submission
      effect: write
      questions:
      - How does a payment processor atomically claim a one-use execution permit before submitting?
      - What happens if two executors try to redeem the same permit at the same time?
      - Can a permit be redeemed while the account-wide execution interlock is paused?
      instructions:
      - text: Redeem execution permit {compact} for request {expected_request} with idempotency key {idempotency_key}.
        slots:
          compact: requestBody.compact
          expected_request: requestBody.expected_request
          idempotency_key: requestBody.idempotency_key
      - text: Claim permit {compact} against the exact signed request {expected_request}, sending Idempotency-Key {key}.
        slots:
          compact: requestBody.compact
          expected_request: requestBody.expected_request
          key: header.Idempotency-Key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/provider-submissions'].post
  update:
    x-apievangelist-phrasing:
      intent: Report a provider payment attempt for reconciliation
      effect: write
      questions:
      - How do I report what happened when my processor submitted a payment to the provider?
      - Does MandateShield trust my reported outcome, or does it check Stripe and x402 evidence itself?
      - What do I need to record a provider attempt, like the permit, claim and payment reference?
      instructions:
      - text: 'Report provider submission {provider_submission_id} for permit {permit_id} and claim {claim_id}: payment {payment_reference} ended {outcome} at {occurred_at}.'
        slots:
          provider_submission_id: requestBody.provider_submission_id
          permit_id: requestBody.permit_id
          claim_id: requestBody.claim_id
          payment_reference: requestBody.payment_reference
          outcome: requestBody.outcome
          occurred_at: requestBody.occurred_at
      - text: Record that payment {payment_reference} under permit {permit_id} was observed as {outcome} and reconcile it.
        slots:
          payment_reference: requestBody.payment_reference
          permit_id: requestBody.permit_id
          outcome: requestBody.outcome
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/provider-webhooks/stripe/{connectionId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Receive a Stripe webhook to trigger reconciliation
      effect: write
      questions:
      - Where should Stripe send webhook events so payments get reconciled?
      - Is a Stripe webhook treated as proof of settlement or just a reconciliation hint?
      - How are duplicate or stale Stripe events handled on the webhook receiver?
      instructions:
      - text: Deliver this Stripe event to connection {connectionId} with signature {signature}.
        slots:
          connectionId: path.connectionId
          signature: header.Stripe-Signature
      - text: Trigger Stripe reconciliation for connection {connectionId} from a signed webhook event.
        slots:
          connectionId: path.connectionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/execution-receipts/verify'].post
  update:
    x-apievangelist-phrasing:
      intent: Verify a terminal execution receipt
      effect: read
      questions:
      - How do I verify a signed receipt proving how a payment execution finally ended?
      - Does a valid terminal execution receipt authorize any further execution?
      - When is a receipt marked as independently verified rather than caller asserted?
      instructions:
      - text: Verify terminal execution receipt {compact}.
        slots:
          compact: requestBody.compact
      - text: Check execution receipt {compact} and require its audience to be {expected_audience}.
        slots:
          compact: requestBody.compact
          expected_audience: requestBody.expected_audience
      method: generated
      generated: '2026-09-26'