# 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 Agents API
  version: 1.0.0
extends: openapi/scope3-storefront-agents-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['/agents'].get
  update:
    x-apievangelist-phrasing:
      intent: List agents registered to my storefront
      effect: read
      questions:
      - Which sales, signals and outcomes agents are registered to my storefront?
      - Can I filter registered agents to those that support registration?
      instructions:
      - text: List the agents registered to my storefront.
      - text: Show registered agents of type {type} with status {status}.
        slots:
          type: query.type
          status: query.status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agents/{agentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a registered agent's details
      effect: read
      questions:
      - What capabilities and account counts does a registered agent have?
      - Can I see if an agent has master or customer account flags?
      instructions:
      - text: Get agent {agentId}.
        slots:
          agentId: path.agentId
      - text: Show capabilities for agent {agentId}.
        slots:
          agentId: path.agentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agents/{agentId}/oauth/authorize'].post
  update:
    x-apievangelist-phrasing:
      intent: Start agent-level OAuth setup
      effect: write
      questions:
      - How do I authorize the platform to call an agent with OAuth?
      - Where are tokens kept after agent-level OAuth?
      instructions:
      - text: Start OAuth for agent {agentId}.
        slots:
          agentId: path.agentId
      - text: Begin agent-level OAuth for {agentId} redirecting to {redirectUri}.
        slots:
          agentId: path.agentId
          redirectUri: requestBody.redirectUri
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agents/{agentId}/accounts/oauth/authorize'].post
  update:
    x-apievangelist-phrasing:
      intent: Start per-account agent OAuth
      effect: write
      questions:
      - Can I authorize an agent separately for each buyer account?
      - How do I register a buyer account with an agent via OAuth?
      instructions:
      - text: Start per-account OAuth on agent {agentId} for account {accountIdentifier}.
        slots:
          agentId: path.agentId
          accountIdentifier: requestBody.accountIdentifier
      - text: Begin account OAuth for agent {agentId}, redirecting to {redirectUri}.
        slots:
          agentId: path.agentId
          redirectUri: requestBody.redirectUri
      method: generated
      generated: '2026-10-01'
- target: $.paths['/agents/{agentId}/capabilities/refresh'].post
  update:
    x-apievangelist-phrasing:
      intent: Refresh an agent's capabilities
      effect: write
      questions:
      - How do I pick up new tools or formats an agent added?
      - Can I re-probe an agent to update its stored capabilities?
      instructions:
      - text: Refresh capabilities for agent {agentId}.
        slots:
          agentId: path.agentId
      - text: Re-probe agent {agentId} and update its protocols and tools.
        slots:
          agentId: path.agentId
      method: generated
      generated: '2026-10-01'