# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely Graph 🏆 Pinned Results API
  version: 1.0.0
extends: openapi/optimizely-pinned-results-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: 12
- target: $.paths['/api/pinned/collections'].get
  update:
    x-apievangelist-phrasing:
      intent: List pinned collections
      effect: read
      questions:
      - Which pinned result collections exist in my search index?
      - Can I page through all pinned collections?
      instructions:
      - text: List pinned collections.
      - text: Show page {page} of pinned collections.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/pinned/collections'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a pinned collection
      effect: write
      questions:
      - How do I set up a new collection for pinned search results?
      - Can I create a pinned collection that starts inactive?
      instructions:
      - text: Create pinned collection {title} with key {key}.
        slots:
          title: requestBody.title
          key: requestBody.key
      - text: Register pinned collection {title}, key {key}, active {isActive}.
        slots:
          title: requestBody.title
          key: requestBody.key
          isActive: requestBody.isActive
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/pinned/collections/{collectionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a pinned collection
      effect: read
      questions:
      - How do I look up one pinned collection by its id?
      - Is a particular pinned collection active?
      instructions:
      - text: Get pinned collection {collectionId}.
        slots:
          collectionId: path.collectionId
      - text: Show details of pinned collection {collectionId}.
        slots:
          collectionId: path.collectionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/pinned/collections/{collectionId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a pinned collection
      effect: write
      questions:
      - How do I rename a pinned collection or turn it off?
      - Can I change a pinned collection's key?
      instructions:
      - text: Rename pinned collection {collectionId} to {title}.
        slots:
          collectionId: path.collectionId
          title: requestBody.title
      - text: Set pinned collection {collectionId} active to {isActive}.
        slots:
          collectionId: path.collectionId
          isActive: requestBody.isActive
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/pinned/collections/{collectionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a pinned collection
      effect: destructive
      questions:
      - How do I delete an entire pinned collection?
      - Can I get rid of a pinned collection I no longer use?
      instructions:
      - text: Delete pinned collection {collectionId}.
        slots:
          collectionId: path.collectionId
      - text: Remove the whole pinned collection {collectionId}.
        slots:
          collectionId: path.collectionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/pinned/collections/{collectionId}/items'].get
  update:
    x-apievangelist-phrasing:
      intent: List pinned items in a collection
      effect: read
      questions:
      - Which items are pinned inside a given collection?
      - Can I filter pinned items in a collection by phrase and sort them?
      instructions:
      - text: List pinned items in collection {collectionId}.
        slots:
          collectionId: path.collectionId
      - text: List pinned items in collection {collectionId} matching phrase {phrase}.
        slots:
          collectionId: path.collectionId
          phrase: query.phrase
      - text: Show {limit} pinned items from collection {collectionId} sorted by {sort}.
        slots:
          limit: query.limit
          collectionId: path.collectionId
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/pinned/collections/{collectionId}/items'].post
  update:
    x-apievangelist-phrasing:
      intent: Pin a document to search phrases
      effect: write
      questions:
      - How do I pin a specific document to the top of results for a search phrase?
      - Can I make a pinned result apply only to one language?
      instructions:
      - text: Pin document {targetKey} for phrases {phrases} in collection {collectionId}.
        slots:
          targetKey: requestBody.targetKey
          phrases: requestBody.phrases
          collectionId: path.collectionId
      - text: Pin document {targetKey} for {phrases} in collection {collectionId}, language {language}, priority {priority}.
        slots:
          targetKey: requestBody.targetKey
          phrases: requestBody.phrases
          collectionId: path.collectionId
          language: requestBody.language
          priority: requestBody.priority
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/pinned/collections/{collectionId}/items'].delete
  update:
    x-apievangelist-phrasing:
      intent: Clear all pinned items in a collection
      effect: destructive
      questions:
      - How do I wipe every pinned item from a collection but keep the collection?
      - Can I empty a pinned collection in one call?
      instructions:
      - text: Clear all pinned items in collection {collectionId}.
        slots:
          collectionId: path.collectionId
      - text: Empty pinned collection {collectionId} of its items.
        slots:
          collectionId: path.collectionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/pinned/collections/{collectionId}/items/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a pinned item
      effect: read
      questions:
      - How do I read the phrases and target document of one pinned item?
      - What priority does a specific pinned item have?
      instructions:
      - text: Get pinned item {id} in collection {collectionId}.
        slots:
          collectionId: path.collectionId
          id: path.id
      - text: Show pinned item {id} from collection {collectionId}.
        slots:
          collectionId: path.collectionId
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/pinned/collections/{collectionId}/items/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a pinned item
      effect: write
      questions:
      - How do I change which document a pinned item points to?
      - Can I change the phrases or priority on an existing pinned item?
      instructions:
      - text: Update pinned item {id} in collection {collectionId} to pin {targetKey} for {phrases}.
        slots:
          id: path.id
          collectionId: path.collectionId
          targetKey: requestBody.targetKey
          phrases: requestBody.phrases
      - text: Set priority {priority} on pinned item {id} in collection {collectionId}, phrases {phrases}, target {targetKey}.
        slots:
          priority: requestBody.priority
          id: path.id
          collectionId: path.collectionId
          phrases: requestBody.phrases
          targetKey: requestBody.targetKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/pinned/collections/{collectionId}/items/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a pinned item
      effect: destructive
      questions:
      - How do I unpin a single document from a collection?
      - Can I remove one pinned item without clearing the rest?
      instructions:
      - text: Remove pinned item {id} from collection {collectionId}.
        slots:
          collectionId: path.collectionId
          id: path.id
      - text: Unpin item {id} in collection {collectionId}.
        slots:
          collectionId: path.collectionId
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/pinned/results'].post
  update:
    x-apievangelist-phrasing:
      intent: Find pinned results for a phrase
      effect: read
      questions:
      - Which documents are pinned for a given search phrase?
      - Can I check pinned matches for a phrase across specific collections and languages?
      instructions:
      - text: Get pinned results for phrase {phrase}.
        slots:
          phrase: requestBody.phrase
      - text: Find active pinned results for {phrase} in collections {collectionKeys}, languages {languages}.
        slots:
          phrase: requestBody.phrase
          collectionKeys: requestBody.collectionKeys
          languages: requestBody.languages
      method: generated
      generated: '2026-09-26'