# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Admin API V1 Page Versions API
  version: 1.0.0
extends: openapi/optimizely-page-versions-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: 9
- target: $.paths['/api/v1/admin/PageVersions'].get
  update:
    x-apievangelist-phrasing:
      intent: List storefront page versions
      effect: read
      questions:
      - Which versions of my storefront pages are waiting for approval?
      - Can I filter page versions by page and sort them by publish date?
      instructions:
      - text: List all page versions.
      - text: List page versions matching {filter}, sorted by {orderby}.
        slots:
          filter: query.$filter
          orderby: query.$orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/PageVersions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a page version
      effect: write
      questions:
      - How do I save a new version of a storefront page scheduled to publish later?
      - Can a new page version be flagged as waiting for approval or as a rollback?
      instructions:
      - text: Create a version of page {pageId} that publishes on {publishOn}.
        slots:
          pageId: requestBody.pageId
          publishOn: requestBody.publishOn
      - text: 'Save a new version of page {pageId} waiting for approval: {isWaitingForApproval}.'
        slots:
          pageId: requestBody.pageId
          isWaitingForApproval: requestBody.isWaitingForApproval
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/PageVersions({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one page version
      effect: read
      questions:
      - How do I read a single page version, including who published it?
      - Can I pull just the stored value of one page version?
      instructions:
      - text: Get page version {id}.
        slots:
          id: path.id
      - text: Show fields {select} of page version {id}.
        slots:
          select: query.$select
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/PageVersions({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a page version
      effect: write
      questions:
      - How do I overwrite a page version record completely?
      - Does a full replace of a page version clear fields I don't send?
      instructions:
      - text: Replace page version {id} for page {pageId} with value {value}.
        slots:
          id: path.id
          pageId: requestBody.pageId
          value: requestBody.value
      - text: Fully overwrite page version {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/PageVersions({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a page version
      effect: destructive
      questions:
      - How do I discard an unwanted page version?
      - Can I delete a page version only if its ETag still matches?
      instructions:
      - text: Delete page version {id}.
        slots:
          id: path.id
      - text: Delete page version {id} guarded by ETag {ifMatch}.
        slots:
          id: path.id
          ifMatch: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/PageVersions({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Reschedule or approve a page version
      effect: write
      questions:
      - Can I change only the publish date of a scheduled page version?
      - How do I clear the waiting-for-approval flag on a page version?
      instructions:
      - text: Reschedule page version {id} to publish on {publishOn}.
        slots:
          id: path.id
          publishOn: requestBody.publishOn
      - text: Set waiting-for-approval to {isWaitingForApproval} on page version {id}.
        slots:
          isWaitingForApproval: requestBody.isWaitingForApproval
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/PageVersions/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Call the Default function on page versions
      effect: read
      questions:
      - What does the Default OData function on page versions return?
      - Is there a default page version entity I can read?
      instructions:
      - text: Call the Default function on page versions.
      - text: Get the default page version entity.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/pageversions/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete page versions
      effect: destructive
      questions:
      - Can I clean up many old page versions in one call?
      - How do I delete a list of page versions by ID?
      instructions:
      - text: Bulk delete page versions {ids}.
        slots:
          ids: query.ids
      - text: 'Clear out these page versions: {ids}.'
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/pageversions({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a page version
      effect: read
      questions:
      - How do I read a custom property stored on a page version?
      - Can page versions carry their own custom fields?
      instructions:
      - text: Get custom property {custompropertyKey} of page version {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Read custom field {custompropertyKey} on page version {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      method: generated
      generated: '2026-09-26'