# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for dotCMS REST Page API
  version: 1.0.0
extends: openapi/dotcms-page-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: 18
- target: $.paths['/api/v1/page/{pageId}/content'].post
  update:
    x-apievangelist-phrasing:
      intent: Replace which content sits in a page's containers
      effect: write
      questions:
      - How do I set exactly which contentlets appear in each container on a page?
      - Does saving page content remove anything I leave out of a container slot?
      instructions:
      - text: Replace the container content mapping on page {pageId}.
        slots:
          pageId: path.pageId
      - text: Set the content layout of page {pageId} for variant {variantName}.
        slots:
          pageId: path.pageId
          variantName: query.variantName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/{pageId}/languages'].get
  update:
    x-apievangelist-phrasing:
      intent: Check which languages a page exists in
      effect: read
      questions:
      - Which languages is this page already translated into?
      - Is there an older endpoint that flags page availability per language?
      instructions:
      - text: List the languages page {pageId} is available in.
        slots:
          pageId: path.pageId
      - text: Check which language versions exist for page {pageId}.
        slots:
          pageId: path.pageId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/_check-permission'].post
  update:
    x-apievangelist-phrasing:
      intent: Check a user's permission on a page
      effect: read
      questions:
      - Can the current user edit or publish a given page path?
      - What permission is checked by default when I test access to a page?
      instructions:
      - text: Check whether I have {type} permission on page {path}.
        slots:
          type: requestBody.type
          path: requestBody.path
      - text: Verify I can read page {path} on site {hostId}.
        slots:
          path: requestBody.path
          hostId: requestBody.hostId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/copyContent'].put
  update:
    x-apievangelist-phrasing:
      intent: Copy a contentlet placed on a page
      effect: write
      questions:
      - Can I duplicate a single contentlet that's already placed on a page?
      - What gets returned when I copy content inside a page container?
      instructions:
      - text: Copy contentlet {contentId} in container {containerId} on page {pageId}.
        slots:
          contentId: requestBody.contentId
          containerId: requestBody.containerId
          pageId: requestBody.pageId
      - text: Make an editable copy of content {contentId} used on page {pageId}.
        slots:
          contentId: requestBody.contentId
          pageId: requestBody.pageId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/{pageId}/_deepcopy'].put
  update:
    x-apievangelist-phrasing:
      intent: Deep copy a page and all its content
      effect: write
      questions:
      - How do I clone a page along with copies of every contentlet on it?
      - Does a deep copy duplicate the page's content or just link to it?
      instructions:
      - text: Deep copy page {pageId} including all its content.
        slots:
          pageId: path.pageId
      - text: Clone page {pageId} with fresh copies of every contentlet.
        slots:
          pageId: path.pageId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/actions'].post
  update:
    x-apievangelist-phrasing:
      intent: Find workflow actions available for a page
      effect: read
      questions:
      - What workflow actions can I take on the page at a given path?
      - Can I get a page's properties and its available actions together?
      instructions:
      - text: List the workflow actions available for page {path}.
        slots:
          path: requestBody.path
      - text: Show page {path} on site {hostId} with its available workflow actions.
        slots:
          path: requestBody.path
          hostId: requestBody.hostId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/{pageId}/content/tree'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a page's container-to-content structure
      effect: read
      questions:
      - Which contentlets are placed in which containers on this page?
      - Can I see the multi-tree mapping and order of content on a page?
      instructions:
      - text: Show the content tree of page {pageId}.
        slots:
          pageId: path.pageId
      - text: Get the container and contentlet positions for page {pageId}.
        slots:
          pageId: path.pageId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/{pageId}/render/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: Compare a page's live and preview versions
      effect: read
      questions:
      - Does my page have unpublished changes compared to the live version?
      - Can I render both the live and working versions of a page at once?
      instructions:
      - text: Compare live and preview renders of page {pageId}.
        slots:
          pageId: path.pageId
      - text: Check if page {pageId} differs between live and working in language {langId}.
        slots:
          pageId: path.pageId
          langId: query.langId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/types'].get
  update:
    x-apievangelist-phrasing:
      intent: List content types that act as pages
      effect: read
      questions:
      - Which content types can render as pages, including URL-mapped ones?
      - Can I filter and page through page-capable content types?
      instructions:
      - text: List all content types that are pages or have URL map patterns.
      - text: Find page content types matching {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/{pageId}/personas'].get
  update:
    x-apievangelist-phrasing:
      intent: List personas personalized on a page
      effect: read
      questions:
      - Which personas have their own content variation on this page?
      - Can I tell which personas are still using the default page content?
      instructions:
      - text: List personas and whether each is personalized on page {pageId}.
        slots:
          pageId: path.pageId
      - text: Show personalized personas on page {pageId} for site {hostId}.
        slots:
          pageId: path.pageId
          hostId: query.hostId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/_render-sources/{uri}'].get
  update:
    x-apievangelist-phrasing:
      intent: Map a rendered page to its source files
      effect: read
      questions:
      - Which template, theme and container files make up a rendered page?
      - Can I get source file references for a page without the file contents?
      instructions:
      - text: List the source files behind page {uri}.
        slots:
          uri: path.uri
      - text: Show render sources for {uri} on site {host_id} for persona {persona_id}.
        slots:
          uri: path.uri
          host_id: query.host_id
          persona_id: query.persona_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/json/{uri}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a page's metadata as JSON
      effect: read
      questions:
      - Can I get the objects that make up a page as JSON without rendered HTML?
      - What did this page look like on a past date using Time Machine?
      instructions:
      - text: Get the page metadata JSON for {uri}.
        slots:
          uri: path.uri
      - text: Fetch unrendered page JSON for {uri} as of {publishDate}.
        slots:
          uri: path.uri
          publishDate: query.publishDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/render/{uri}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a page with its rendered HTML and content
      effect: read
      questions:
      - How do I fetch a page for headless use with its containers already rendered?
      - Can I render a page as a specific persona in a given language?
      instructions:
      - text: Render page {uri} with its container content as JSON.
        slots:
          uri: path.uri
      - text: Render {uri} in language {language_id} for persona {persona}.
        slots:
          uri: path.uri
          language_id: query.language_id
          persona: query.com.dotmarketing.persona.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/renderHTML/{uri}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a page's raw rendered HTML
      effect: read
      questions:
      - Can I get just the final HTML of a page without any JSON wrapper?
      - What returns a page's raw markup for server-side embedding?
      instructions:
      - text: Give me the raw HTML of page {uri}.
        slots:
          uri: path.uri
      - text: Render {uri} on site {host_id} as plain HTML in {mode} mode.
        slots:
          uri: path.uri
          host_id: query.host_id
          mode: query.mode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/layout'].post
  update:
    x-apievangelist-phrasing:
      intent: Save a page template layout
      effect: write
      questions:
      - How do I save a new template layout with rows and columns?
      - Can I save a template layout with a theme before attaching it to any page?
      instructions:
      - text: Save template layout {layout} titled {title}.
        slots:
          layout: requestBody.layout
          title: requestBody.title
      - text: Save a template with layout {layout} using theme {themeId} on site {siteId}.
        slots:
          layout: requestBody.layout
          themeId: requestBody.themeId
          siteId: requestBody.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/{pageId}/layout'].post
  update:
    x-apievangelist-phrasing:
      intent: Link a template layout to a page
      effect: write
      questions:
      - How do I apply a layout to a specific page?
      - What happens to a page's existing template when I link a new layout?
      instructions:
      - text: Apply layout {layout} to page {pageId}.
        slots:
          layout: requestBody.layout
          pageId: path.pageId
      - text: Link layout {layout} to page {pageId} for variant {variantName}.
        slots:
          layout: requestBody.layout
          pageId: path.pageId
          variantName: query.variantName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search pages by path
      effect: read
      questions:
      - Which pages have a path containing a given word?
      - Can I limit a page path search to live pages on live sites?
      instructions:
      - text: Find pages whose path matches {path}.
        slots:
          path: query.path
      - text: Search live pages only for path {path}.
        slots:
          path: query.path
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/page/{pageId}/styles'].put
  update:
    x-apievangelist-phrasing:
      intent: Update style properties of content on a page
      effect: write
      questions:
      - Can I change the styling of a contentlet on a page without touching the layout?
      - Are style changes on page content scoped to a persona?
      instructions:
      - text: Update styles for contentlet {identifier} in container slot {uuid} on page {pageId}.
        slots:
          identifier: requestBody.identifier
          uuid: requestBody.uuid
          pageId: path.pageId
      - text: Restyle content {identifier} in slot {uuid} on page {pageId} for persona {personaTag}.
        slots:
          identifier: requestBody.identifier
          uuid: requestBody.uuid
          pageId: path.pageId
          personaTag: requestBody.personaTag
      method: generated
      generated: '2026-09-26'