# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely Personas API
  version: 1.0.0
extends: openapi/optimizely-personas-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: 14
- target: $.paths['/api/v1/admin/Personas'].get
  update:
    x-apievangelist-phrasing:
      intent: List personalization personas
      effect: read
      questions:
      - How do I list every persona set up for personalization in Optimizely Configured Commerce?
      - Can I filter the persona list, say to only default personas, and count the results?
      instructions:
      - text: List all personas.
      - text: List personas matching {filter}, returning the first {top}.
        slots:
          filter: query.$filter
          top: query.$top
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Personas'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a persona
      effect: write
      questions:
      - What do I need to define a new shopper persona with a name and description?
      - Can a new persona be auto-assigned to guest users after a minimum number of actions?
      instructions:
      - text: Create a persona named {name} described as {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      - text: Add persona {name} ({description}) that activates on {activateOn} and boosts search by {boostValue}.
        slots:
          name: requestBody.name
          description: requestBody.description
          activateOn: requestBody.activateOn
          boostValue: requestBody.boostValue
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Personas({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a persona by ID
      effect: read
      questions:
      - How can I see the settings of one persona, like its activation dates and boost value?
      - Which related records can I expand when reading a single persona?
      instructions:
      - text: Show persona {id}.
        slots:
          id: path.id
      - text: Get persona {id} with {expand} expanded.
        slots:
          id: path.id
          expand: query.$expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Personas({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a persona record
      effect: write
      questions:
      - Can I overwrite a persona with a full new definition in one call?
      - Do I have to resend the persona's name and description when replacing the whole record?
      instructions:
      - text: Replace persona {id} with name {name} and description {description}.
        slots:
          id: path.id
          name: requestBody.name
          description: requestBody.description
      - text: Overwrite persona {id} entirely, setting its deactivation date to {deactivateOn}.
        slots:
          id: path.id
          deactivateOn: requestBody.deactivateOn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Personas({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one persona
      effect: destructive
      questions:
      - How do I permanently delete a single persona?
      - Can I guard a persona delete with an If-Match ETag?
      instructions:
      - text: Delete persona {id}.
        slots:
          id: path.id
      - text: Delete persona {id} if its ETag is still {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Personas({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update part of a persona
      effect: write
      questions:
      - Can I turn on search boosting for an existing persona without replacing it?
      - How do I change only a persona's sequence or boost value?
      instructions:
      - text: Patch persona {id} to enable search boost with value {boostValue}.
        slots:
          id: path.id
          boostValue: requestBody.boostValue
      - text: Update persona {id} so its sequence is {sequence}.
        slots:
          id: path.id
          sequence: requestBody.sequence
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Personas/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get default values for a new persona
      effect: read
      questions:
      - What defaults does the admin API fill in for a persona before it's created?
      - Is there a blank persona template to start from?
      instructions:
      - text: Get the default persona template.
      - text: Show the pre-filled values for a new persona.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Personas/Default.archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive personas (OData action)
      effect: write
      questions:
      - Can I archive personas I no longer use instead of deleting them, via the Default.archive action?
      - How do I archive several personas with the POST archive action?
      instructions:
      - text: Archive personas {ids} using the Default.archive POST action.
        slots:
          ids: query.ids
      - text: POST to the persona archive action for IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/personas/archive'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive personas (DELETE route)
      effect: destructive
      questions:
      - Is there a DELETE-style personas/archive route for archiving personas?
      - Which endpoint archives personas using the HTTP DELETE verb?
      instructions:
      - text: Archive personas {ids} through the DELETE personas/archive route.
        slots:
          ids: query.ids
      - text: Send a DELETE to the persona archive route for {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/personas/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete several personas at once
      effect: destructive
      questions:
      - Can I bulk delete a list of personas in one call?
      - How do I permanently remove multiple personas rather than archiving them?
      instructions:
      - text: Bulk delete personas {ids}.
        slots:
          ids: query.ids
      - text: Permanently remove all personas in {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/personas({key})/categories({categoryKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a category assigned to a persona
      effect: read
      questions:
      - How do I check a specific category tied to a persona?
      - Which category records are linked to a persona for personalization?
      instructions:
      - text: Get category {categoryKey} of persona {key}.
        slots:
          categoryKey: path.categoryKey
          key: path.key
      - text: Show persona {key}'s linked category {categoryKey}.
        slots:
          key: path.key
          categoryKey: path.categoryKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/personas({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a persona
      effect: read
      questions:
      - Can I read one custom property value stored on a persona?
      - Where do I find custom attributes my team added to a persona?
      instructions:
      - text: Get custom property {custompropertyKey} on persona {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show persona {key}'s custom property {custompropertyKey}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/personas({key})/userprofiles({userprofileKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user profile assigned to a persona
      effect: read
      questions:
      - Is a particular user profile assigned to a given persona?
      - How do I read one user profile under a persona?
      instructions:
      - text: Get user profile {userprofileKey} under persona {key}.
        slots:
          userprofileKey: path.userprofileKey
          key: path.key
      - text: Check whether persona {key} includes user profile {userprofileKey}.
        slots:
          key: path.key
          userprofileKey: path.userprofileKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/personas/calculate'].get
  update:
    x-apievangelist-phrasing:
      intent: Calculate the current shopper's personas
      effect: read
      questions:
      - Which personas apply to the shopper in the current storefront session?
      - What endpoint works out personas for the signed-in user?
      instructions:
      - text: Calculate personas for the current session.
      - text: Work out which personas the current shopper matches.
      method: generated
      generated: '2026-09-26'