# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely Campaign REST Custom blocklists API
  version: 1.0.0
extends: openapi/optimizely-custom-blocklists-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: 10
- target: $.paths['/{clientId}/customblacklists'].get
  update:
    x-apievangelist-phrasing:
      intent: List custom blocklists
      effect: read
      questions:
      - Which custom blocklists does my Optimizely client have, and what hash algorithm does each use?
      - Can I limit the blocklists returned to one folder?
      instructions:
      - text: List custom blocklists for client {clientId}.
        slots:
          clientId: path.clientId
      - text: List up to {limit} custom blocklists in folder {folderId} for client {clientId}.
        slots:
          limit: query.limit
          folderId: query.folderId
          clientId: path.clientId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/customblacklists'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom blocklist
      effect: write
      questions:
      - How do I create a new blocklist to keep certain recipients out of mailings?
      - Can a custom blocklist store hashed patterns instead of plain ones?
      instructions:
      - text: Create a custom blocklist named {name} for client {clientId}.
        slots:
          name: requestBody.name
          clientId: path.clientId
      - text: Create blocklist {name} for client {clientId} using hash algorithm {hashAlgorithm}.
        slots:
          name: requestBody.name
          clientId: path.clientId
          hashAlgorithm: requestBody.hashAlgorithm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/customblacklists/{customBlacklistId}/entries'].get
  update:
    x-apievangelist-phrasing:
      intent: List entries in a custom blocklist
      effect: read
      questions:
      - What patterns are in a custom blocklist, and why was each blocked?
      - Can I search a blocklist's entries for a matching pattern?
      - Is there a way to page and sort blocklist entries by creation date?
      instructions:
      - text: List entries in blocklist {customBlacklistId} for client {clientId}.
        slots:
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
      - text: Find entries in blocklist {customBlacklistId} of client {clientId} matching {matchingPattern}.
        slots:
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
          matchingPattern: query.matchingPattern
      - text: Check if blocklist {customBlacklistId} for client {clientId} has the exact pattern {exactPattern}.
        slots:
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
          exactPattern: query.exactPattern
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/customblacklists/{customBlacklistId}/entries'].post
  update:
    x-apievangelist-phrasing:
      intent: Add patterns to a custom blocklist
      effect: write
      questions:
      - How do I block new email addresses or domains by adding them to a blocklist?
      - Can I record a reason when adding blocklist patterns?
      instructions:
      - text: Add patterns {patterns} to blocklist {customBlacklistId} for client {clientId}.
        slots:
          patterns: requestBody.patterns
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
      - text: Block {patterns} in blocklist {customBlacklistId} of client {clientId} with reason {reason}.
        slots:
          patterns: requestBody.patterns
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
          reason: requestBody.reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/customblacklists/{customBlacklistId}/entries'].delete
  update:
    x-apievangelist-phrasing:
      intent: Clear all entries from a custom blocklist
      effect: destructive
      questions:
      - How do I empty a blocklist completely while keeping the list itself?
      - Can I wipe every pattern from a custom blocklist at once?
      instructions:
      - text: Remove all entries from blocklist {customBlacklistId} for client {clientId}.
        slots:
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
      - text: Wipe blocklist {customBlacklistId} of client {clientId} clean.
        slots:
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/customblacklists/{customBlacklistId}/entries/{customBlacklistEntryId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one custom blocklist entry
      effect: read
      questions:
      - When was a specific blocklist entry created and for what reason?
      - How do I read a single entry of a custom blocklist?
      instructions:
      - text: Get entry {customBlacklistEntryId} of blocklist {customBlacklistId} for client {clientId}.
        slots:
          customBlacklistEntryId: path.customBlacklistEntryId
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
      - text: Show why entry {customBlacklistEntryId} is in blocklist {customBlacklistId} (client {clientId}).
        slots:
          customBlacklistEntryId: path.customBlacklistEntryId
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/customblacklists/{customBlacklistId}/entries/{customBlacklistEntryId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a custom blocklist entry's reason
      effect: write
      questions:
      - How do I change the reason recorded on a blocklist entry?
      - Can I edit an existing blocklist entry instead of recreating it?
      instructions:
      - text: Set the reason on entry {customBlacklistEntryId} in blocklist {customBlacklistId} for client {clientId} to {reason}.
        slots:
          customBlacklistEntryId: path.customBlacklistEntryId
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
          reason: requestBody.reason
      - text: Update blocklist entry {customBlacklistEntryId} in list {customBlacklistId} of client {clientId}.
        slots:
          customBlacklistEntryId: path.customBlacklistEntryId
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/customblacklists/{customBlacklistId}/entries/{customBlacklistEntryId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove one entry from a custom blocklist
      effect: destructive
      questions:
      - How do I unblock a single address by deleting its blocklist entry?
      - Can I remove just one pattern from a blocklist?
      instructions:
      - text: Delete entry {customBlacklistEntryId} from blocklist {customBlacklistId} for client {clientId}.
        slots:
          customBlacklistEntryId: path.customBlacklistEntryId
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
      - text: Unblock entry {customBlacklistEntryId} in blocklist {customBlacklistId} of client {clientId}.
        slots:
          customBlacklistEntryId: path.customBlacklistEntryId
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/customblacklists/{customBlacklistId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom blocklist
      effect: read
      questions:
      - What is the name and hash algorithm of a specific blocklist?
      - How do I fetch details of one custom blocklist?
      instructions:
      - text: Get blocklist {customBlacklistId} for client {clientId}.
        slots:
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
      - text: Show the hash algorithm of blocklist {customBlacklistId} (client {clientId}).
        slots:
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{clientId}/customblacklists/{customBlacklistId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Rename or rehash a custom blocklist
      effect: write
      questions:
      - How do I rename an existing custom blocklist?
      - Can I change the hash algorithm a blocklist uses?
      instructions:
      - text: Rename blocklist {customBlacklistId} for client {clientId} to {name}.
        slots:
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
          name: requestBody.name
      - text: 'Update blocklist {customBlacklistId} of client {clientId}: name {name}, hash algorithm {hashAlgorithm}.'
        slots:
          customBlacklistId: path.customBlacklistId
          clientId: path.clientId
          name: requestBody.name
          hashAlgorithm: requestBody.hashAlgorithm
      method: generated
      generated: '2026-09-26'