# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely Content API
  version: 1.0.0
extends: openapi/optimizely-content-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: 27
- target: $.paths['/content'].get
  update:
    x-apievangelist-phrasing:
      intent: List items in the CMP content repository
      effect: read
      questions:
      - What content items are sitting in my Optimizely CMP content repository?
      - Can I page through the CMP content library with a limit and offset?
      instructions:
      - text: List everything in the CMP content repository.
      - text: Show {limit} CMP content items starting after the first {offset}.
        slots:
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/content'].post
  update:
    x-apievangelist-phrasing:
      intent: Import a content item from a URL
      effect: write
      questions:
      - How do I ingest an article into the content library just by giving its URL?
      - Does importing content from a link happen right away or is it queued?
      instructions:
      - text: Import the page at {original_url} as a new content item.
        slots:
          original_url: requestBody.original_url
      - text: Queue {original_url} for content ingestion.
        slots:
          original_url: requestBody.original_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/content/{contentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a CMP content item's details
      effect: read
      questions:
      - How can I look up the details of a single item in the CMP content repository?
      - What does the CMP return for one content item when I know its content ID?
      instructions:
      - text: Get CMP content item {contentId}.
        slots:
          contentId: path.contentId
      - text: Show me the repository details for CMP content {contentId}.
        slots:
          contentId: path.contentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/content/PageByType'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a storefront page by its page type
      effect: read
      questions:
      - How do I fetch the storefront page definition for a given page type like the home page?
      - Can I load a Configured Commerce page just by knowing its type name?
      instructions:
      - text: Load the storefront page of type {type}.
        slots:
          type: query.type
      - text: Get the page content for the {type} page type.
        slots:
          type: query.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/content/PagesByParent'].get
  update:
    x-apievangelist-phrasing:
      intent: List storefront pages under a parent node
      effect: read
      questions:
      - Which storefront pages sit underneath a given parent node in the page tree?
      - Can I get all child pages of a node in the commerce site structure?
      instructions:
      - text: List the storefront pages under parent node {parentNodeId}.
        slots:
          parentNodeId: query.parentNodeId
      - text: Show all pages whose parent is node {parentNodeId}.
        slots:
          parentNodeId: query.parentNodeId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/content/PageByUrl'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a storefront page by its URL
      effect: read
      questions:
      - How do I resolve a storefront URL path to the page that renders it?
      - Can I fetch a commerce page's content when all I have is its URL?
      instructions:
      - text: Get the storefront page served at {url}.
        slots:
          url: query.url
      - text: Resolve URL {url} to its page content.
        slots:
          url: query.url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/content/PageUrlByType'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up the URL of a storefront page type
      effect: read
      questions:
      - What URL does the storefront use for a particular page type, say the cart page?
      - Can I find out where a page type lives so I can link to it?
      instructions:
      - text: Give me the URL of the {type} page.
        slots:
          type: query.type
      - text: Find the storefront link for page type {type}.
        slots:
          type: query.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/content/PageLinks'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the storefront's page links for navigation
      effect: read
      questions:
      - How do I pull the set of page links that drive my storefront navigation?
      - Is there a single call that returns the links to all the site's pages?
      instructions:
      - text: Fetch the storefront page links.
      - text: Get the list of page links I need to build the site menu.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/content/GetNodeIdForPageName'].get
  update:
    x-apievangelist-phrasing:
      intent: Find the node ID for a storefront page name
      effect: read
      questions:
      - How do I find the content node ID behind a page when I only know its name?
      - Which node ID corresponds to a named storefront page?
      instructions:
      - text: Look up the node ID for the page named {pageName}.
        slots:
          pageName: query.pageName
      - text: Get the content node for page {pageName}.
        slots:
          pageName: query.pageName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/content/Theme'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the storefront's current theme
      effect: read
      questions:
      - Which theme is my commerce storefront currently using?
      - Can I read the active site theme so my headless front end matches it?
      instructions:
      - text: Get the active storefront theme.
      - text: Tell me which theme the site is set to.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/content/{contentId}/children'].get
  update:
    x-apievangelist-phrasing:
      intent: List child items of a content item
      effect: read
      questions:
      - How do I walk down a CMS page tree to see the items beneath a page?
      - Can I skip and limit results when listing a content item's children in a given language?
      instructions:
      - text: List the child items of content {contentId}.
        slots:
          contentId: path.contentId
      - text: Show {top} children of content {contentId} in {language}, skipping the first {skip}.
        slots:
          top: query.top
          contentId: path.contentId
          language: query.language
          skip: query.skip
      method: generated
      generated: '2026-09-26'
- target: $.paths['/content/{contentId}/ancestors'].get
  update:
    x-apievangelist-phrasing:
      intent: List the ancestors of a content item
      effect: read
      questions:
      - How can I get the chain of parent items from the root down to a content item?
      - What calls give me a breadcrumb trail for a CMS page by its content ID?
      instructions:
      - text: Get the ancestor path for content {contentId}.
        slots:
          contentId: path.contentId
      - text: Build a breadcrumb for content {contentId} in {language}.
        slots:
          contentId: path.contentId
          language: query.language
      method: generated
      generated: '2026-09-26'
- target: $.paths['/'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new content item in the CMS
      effect: write
      questions:
      - How do I create a new page or block of a given content type under a parent in Optimizely CMS?
      - Can I create a language branch of existing content instead of a brand-new item?
      - Is it possible to upload a media file when creating content?
      instructions:
      - text: Create a {contentType} named {name} under parent {parentLink}.
        slots:
          contentType: requestBody.contentType
          name: requestBody.name
          parentLink: requestBody.parentLink
      - text: Create content {name} of type {contentType} under {parentLink}, scheduled to publish at {startPublish}.
        slots:
          name: requestBody.name
          contentType: requestBody.contentType
          parentLink: requestBody.parentLink
          startPublish: requestBody.startPublish
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{contentGuid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a content item by its GUID
      effect: read
      questions:
      - How do I fetch the primary draft or latest published version of content using its GUID?
      - Can I read a CMS item for editing when I only have its GUID?
      instructions:
      - text: Get the content item with GUID {contentGuid}.
        slots:
          contentGuid: path.contentGuid
      - text: Load the current draft of content {contentGuid} for editing.
        slots:
          contentGuid: path.contentGuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{contentGuid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace or upsert a content item by GUID
      effect: write
      questions:
      - How do I overwrite a whole content item by GUID, creating it if it doesn't exist?
      - Will a full update by GUID create new content when nothing matches that GUID?
      instructions:
      - text: Upsert content {contentGuid} as {contentType} named {name} under {parentLink}.
        slots:
          contentGuid: path.contentGuid
          contentType: requestBody.contentType
          name: requestBody.name
          parentLink: requestBody.parentLink
      - text: Fully replace content {contentGuid} and set its status to {status}.
        slots:
          contentGuid: path.contentGuid
          status: requestBody.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{contentGuid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Trash or permanently delete content
      effect: destructive
      questions:
      - How do I delete a CMS item by its GUID?
      - Does deleting content send it to the trash bin, or can I skip the trash and remove it for good?
      instructions:
      - text: Move content {contentGuid} to the trash.
        slots:
          contentGuid: path.contentGuid
      - text: Permanently delete content {contentGuid} with permanent set to {permanent}.
        slots:
          contentGuid: path.contentGuid
          permanent: query.permanent
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{contentGuid}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a few fields on a content item
      effect: write
      questions:
      - Can I update just the name or status of a content item without resending everything?
      - How do I tweak a single property on a CMS page identified by GUID?
      instructions:
      - text: Rename content {contentGuid} to {name}.
        slots:
          contentGuid: path.contentGuid
          name: requestBody.name
      - text: Set only the status of content {contentGuid} to {status}.
        slots:
          contentGuid: path.contentGuid
          status: requestBody.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{contentGuid}/move'].post
  update:
    x-apievangelist-phrasing:
      intent: Move a content item under a new parent
      effect: write
      questions:
      - How do I relocate a page so it becomes a child of a different node?
      - Can I restructure my CMS tree by moving an item to another parent?
      instructions:
      - text: Move content {contentGuid} under {destination}.
        slots:
          contentGuid: path.contentGuid
          destination: requestBody.destination
      - text: Reparent item {contentGuid} to node {destination}.
        slots:
          contentGuid: path.contentGuid
          destination: requestBody.destination
      method: generated
      generated: '2026-09-26'
- target: $.paths['/{contentReference}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a content item by its numeric reference
      effect: read
      questions:
      - How do I fetch a CMS item using its numeric content reference rather than a GUID?
      - What comes back when I look content up by reference ID in the management API?
      instructions:
      - text: Get content by reference {contentReference}.
        slots:
          contentReference: path.contentReference
      - text: Look up the item whose content reference is {contentReference}.
        slots:
          contentReference: path.contentReference
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/episerver/v3.0/content/{contentIdentifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Deliver a content item by reference or GUID
      effect: read
      questions:
      - How do I read published content through the Content Delivery API in a specific language?
      - Can I choose which properties to return or expand when delivering a single content item?
      instructions:
      - text: Deliver content {contentIdentifier} in {language}.
        slots:
          contentIdentifier: path.contentIdentifier
          language: header.Accept-Language
      - text: Fetch delivered content {contentIdentifier} returning only {select}.
        slots:
          contentIdentifier: path.contentIdentifier
          select: query.select
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/episerver/v3.0/content/{contentIdentifier}/children'].get
  update:
    x-apievangelist-phrasing:
      intent: Deliver the children of a content item
      effect: read
      questions:
      - Which children does a page have when read through the Content Delivery API?
      - Can I page children with a continuation token in the delivery API?
      instructions:
      - text: Deliver the children of {contentIdentifier} in {language}.
        slots:
          contentIdentifier: path.contentIdentifier
          language: header.Accept-Language
      - text: Get up to {top} delivered child items of {contentIdentifier}.
        slots:
          top: query.top
          contentIdentifier: path.contentIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/episerver/v3.0/content/{contentIdentifier}/ancestors'].get
  update:
    x-apievangelist-phrasing:
      intent: Deliver the ancestors of a content item
      effect: read
      questions:
      - How do I get a page's parents through the Content Delivery API for site navigation?
      - Can the delivery API return ancestors localized to a given language?
      instructions:
      - text: Deliver the ancestors of {contentIdentifier}.
        slots:
          contentIdentifier: path.contentIdentifier
      - text: List delivered parent pages of {contentIdentifier} in {language}.
        slots:
          contentIdentifier: path.contentIdentifier
          language: header.Accept-Language
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/episerver/v3.0/content'].get
  update:
    x-apievangelist-phrasing:
      intent: Deliver content by URL or a list of IDs
      effect: read
      questions:
      - How do I get published content from its full URL through the delivery API?
      - Can I fetch several content items at once by passing a comma-separated list of GUIDs?
      - Is there a way to require the URL to match exactly with no extra segments?
      instructions:
      - text: Deliver the content at {ContentUrl}, matching the URL exactly.
        slots:
          ContentUrl: query.ContentUrl
      - text: Deliver the content items with GUIDs {Guids}.
        slots:
          Guids: query.Guids
      - text: Deliver content references {References} in {language}.
        slots:
          References: query.References
          language: header.Accept-Language
      method: generated
      generated: '2026-09-26'
- target: $.paths['/content/_filter'].post
  update:
    x-apievangelist-phrasing:
      intent: Search content items with a Lucene query
      effect: read
      questions:
      - How do I filter the content library with a Lucene query?
      - Can content search results include topic information and be paginated?
      instructions:
      - text: Search content matching the Lucene query {query}.
        slots:
          query: requestBody.query
      - text: Run content filter {query} and return page {page} with {rpp} results per page.
        slots:
          query: requestBody.query
          page: query.page
          rpp: query.rpp
      method: generated
      generated: '2026-09-26'
- target: $.paths['/content/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch a recommendations content item by ID
      effect: read
      questions:
      - How do I see the title, abstract and approval status of an ingested content item?
      - Can I check whether an ingested article is featured or approved?
      instructions:
      - text: Fetch ingested content item {id}.
        slots:
          id: path.id
      - text: Show whether content {id} is approved and featured.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/content/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Approve or feature an ingested content item
      effect: write
      questions:
      - How do I mark an ingested article as approved?
      - Which fields can I actually change on a content item - just approved and featured?
      instructions:
      - text: Set approved to {approved} on content {id}.
        slots:
          approved: requestBody.approved
          id: path.id
      - text: 'Mark content {id} as featured: {featured}.'
        slots:
          id: path.id
          featured: requestBody.featured
      method: generated
      generated: '2026-09-26'
- target: $.paths['/content/{id}/sections'].get
  update:
    x-apievangelist-phrasing:
      intent: List the sections that contain a content item
      effect: read
      questions:
      - Which sections is a given content item included in?
      - Can I see every section an article appears in?
      instructions:
      - text: List the sections containing content {id}.
        slots:
          id: path.id
      - text: Show where content {id} is placed across sections.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'