Scope3 · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Scope3 Storefront Storefront Proposals API

6 actions 6 updates phrasing extends openapi/scope3-storefront-proposals-api-openapi.yml

Generated by API Evangelist Written by API Evangelist tooling for Scope3's API. It is a proposal applied on top of the contract, not a document Scope3 publishes.

View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 6

$.info

$.paths['/proposals'].get

$.paths['/proposals'].post

$.paths['/proposals/{id}'].get

$.paths['/proposals/{id}'].patch

$.paths['/proposals/{id}/revoke'].post

OpenAPI Overlay

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Scope3 Storefront Storefront Proposals API
  version: 1.0.0
extends: openapi/scope3-storefront-proposals-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: 5
- target: $.paths['/proposals'].get
  update:
    x-apievangelist-phrasing:
      intent: List my storefront proposals
      effect: read
      questions:
      - Which proposals has my storefront shared with buyers?
      - Can I filter my proposals by status or by the buyer they were made for?
      instructions:
      - text: List my storefront proposals.
      - text: Show {status} proposals for buyer operator {operator_id}.
        slots:
          status: query.status
          operator_id: query.operatorId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/proposals'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a shareable proposal code for a buyer
      effect: write
      questions:
      - Can I package discovered products into a code a buyer can redeem?
      - Does a storefront proposal have to have an expiry date?
      instructions:
      - text: Create proposal {label} for operator {operator_id} from discovery {discovery_id} and proposal {proposal_id}, expiring {expires_at}.
        slots:
          label: requestBody.label
          operator_id: requestBody.operatorId
          discovery_id: requestBody.discoveryId
          proposal_id: requestBody.proposalId
          expires_at: requestBody.expiresAt
      - text: Mint a proposal code for buyer {operator_id} labelled {label} with notes {notes}, using discovery {discovery_id}, proposal {proposal_id}, expiring {expires_at}.
        slots:
          operator_id: requestBody.operatorId
          label: requestBody.label
          notes: requestBody.notes
          discovery_id: requestBody.discoveryId
          proposal_id: requestBody.proposalId
          expires_at: requestBody.expiresAt
      method: generated
      generated: '2026-10-01'
- target: $.paths['/proposals/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: View a storefront proposal
      effect: read
      questions:
      - What products did I include in a proposal I sent a buyer?
      - Can I see the saved discovery response behind one proposal?
      instructions:
      - text: Show storefront proposal {id}.
        slots:
          id: path.id
      - text: Get the saved discovery details for proposal {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/proposals/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a proposal's label, notes or expiry
      effect: write
      questions:
      - Can I extend the expiry date on a proposal I already shared?
      - What can I edit on an existing storefront proposal?
      instructions:
      - text: Extend proposal {id} to expire at {expires_at}.
        slots:
          id: path.id
          expires_at: requestBody.expiresAt
      - text: Rename proposal {id} to {label} and set its notes to {notes}.
        slots:
          id: path.id
          label: requestBody.label
          notes: requestBody.notes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/proposals/{id}/revoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke a storefront proposal
      effect: destructive
      questions:
      - How do I stop a buyer from redeeming a proposal code?
      - Can I revoke a proposal that has already expired?
      instructions:
      - text: Revoke storefront proposal {id}.
        slots:
          id: path.id
      - text: Cancel proposal {id} so its code can no longer be redeemed.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'