# 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 Content Items API
  version: 1.0.0
extends: openapi/optimizely-content-items-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/ContentItems'].get
  update:
    x-apievangelist-phrasing:
      intent: List CMS content items
      effect: read
      questions:
      - Which content items and pages exist on my commerce website's CMS?
      - Can I filter content items to only pages for one website?
      - How many content items are there in total?
      instructions:
      - text: List all content items.
      - text: Find content items matching {filter}.
        slots:
          filter: query.$filter
      - text: Show the first {top} content items ordered by {orderby}.
        slots:
          top: query.$top
          orderby: query.$orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ContentItems'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a content item
      effect: write
      questions:
      - How do I add a new page or widget content item to the CMS?
      - Can I schedule when a new content item publishes?
      instructions:
      - text: Create content item {name} of class {class} at path {path} in zone {zone}.
        slots:
          name: requestBody.name
          class: requestBody.class
          path: requestBody.path
          zone: requestBody.zone
      - text: Add a content item {name} with variant {variantName} and template view {templateView}, publishing on {publishOn}.
        slots:
          name: requestBody.name
          variantName: requestBody.variantName
          templateView: requestBody.templateView
          publishOn: requestBody.publishOn
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ContentItems({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one content item
      effect: read
      questions:
      - What is the publish and approval status of a specific content item?
      - Is a given content item a page or a template?
      instructions:
      - text: Get content item {id}.
        slots:
          id: path.id
      - text: Show content item {id} returning only {select}.
        slots:
          id: path.id
          select: query.$select
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ContentItems({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a content item record
      effect: write
      questions:
      - How do I overwrite a content item with a complete new record?
      - Can I fully replace a CMS content item instead of patching fields?
      instructions:
      - text: Replace content item {id} with name {name}, class {class} and path {path}.
        slots:
          id: path.id
          name: requestBody.name
          class: requestBody.class
          path: requestBody.path
      - text: Overwrite the whole record for content item {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ContentItems({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a content item
      effect: destructive
      questions:
      - How do I remove a single content item from the CMS?
      - Can I delete a content item conditionally on its ETag?
      instructions:
      - text: Delete content item {id}.
        slots:
          id: path.id
      - text: Delete content item {id} if its ETag is still {ifMatch}.
        slots:
          id: path.id
          ifMatch: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ContentItems({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a content item
      effect: write
      questions:
      - Can I change just the publish date of an existing content item?
      - How do I retract a content item without rewriting the whole record?
      instructions:
      - text: Set content item {id} to publish on {publishOn}.
        slots:
          id: path.id
          publishOn: requestBody.publishOn
      - text: Mark content item {id} as retracted {isRetracted}.
        slots:
          id: path.id
          isRetracted: requestBody.isRetracted
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ContentItems/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the default content item template
      effect: read
      questions:
      - What default values does a new content item start with?
      - Is there a blank content item template I can fetch?
      instructions:
      - text: Fetch the default content item template.
      - text: Get default values for a new content item.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/contentitems/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete content items
      effect: destructive
      questions:
      - How do I delete many content items in one request?
      - Can I remove several CMS content items by listing their IDs?
      instructions:
      - text: Bulk delete content items {ids}.
        slots:
          ids: query.ids
      - text: 'Remove all these content items at once: {ids}.'
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/contentitems({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property of a content item
      effect: read
      questions:
      - How do I read a custom property attached to a content item?
      - Can I fetch a single custom field from a CMS content item?
      instructions:
      - text: Get custom property {custompropertyKey} of content item {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show custom field {custompropertyKey} on content item {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      method: generated
      generated: '2026-09-26'