# 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 Portlets API
  version: 1.0.0
extends: openapi/dotcms-portlets-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/portlet/layout/{params}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a portlet's layout (legacy)
      effect: read
      questions:
      - Where does the legacy portlet layout endpoint get the screen layout for a portlet?
      - Can I fetch a portlet's layout definition through the older /api/portlet/layout route?
      instructions:
      - text: Get the legacy portlet layout for {params}.
        slots:
          params: path.params
      - text: Load the layout definition of the portlet described by {params}.
        slots:
          params: path.params
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/portlet/{params}'].get
  update:
    x-apievangelist-phrasing:
      intent: Render a legacy portlet via GET
      effect: read
      questions:
      - Can I load a legacy portlet's content with a plain GET?
      - Which older route returns a portlet by its parameters?
      instructions:
      - text: Load legacy portlet {params} with a GET request.
        slots:
          params: path.params
      - text: Fetch the old-style portlet view for {params}.
        slots:
          params: path.params
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/portlet/{params}'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit to a legacy portlet via POST
      effect: write
      questions:
      - How do I post a form submission to a legacy portlet?
      - Is there a POST variant of the old portlet route?
      instructions:
      - text: Post to legacy portlet {params}.
        slots:
          params: path.params
      - text: Submit data to the old-style portlet at {params} using POST.
        slots:
          params: path.params
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/portlet/custom/{portletId}/_addtolayout/{layoutId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Add a custom portlet to a layout
      effect: write
      questions:
      - How do I put a custom content portlet into a menu layout?
      - Can I add my custom portlet to a specific layout tab?
      instructions:
      - text: Add custom portlet {portletId} to layout {layoutId}.
        slots:
          portletId: path.portletId
          layoutId: path.layoutId
      - text: Place portlet {portletId} in the {layoutId} layout so users see it in the menu.
        slots:
          portletId: path.portletId
          layoutId: path.layoutId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/portlet/custom/{portletId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom content portlet
      effect: destructive
      questions:
      - How do I delete a custom content portlet I created?
      - Can I remove a custom portlet entirely rather than just hiding it from a role?
      instructions:
      - text: Delete custom portlet {portletId}.
        slots:
          portletId: path.portletId
      - text: Permanently remove the custom content portlet {portletId}.
        slots:
          portletId: path.portletId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/portlet/portletId/{portletId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a portlet from my own layout
      effect: destructive
      questions:
      - Can I remove a portlet from just my personal menu?
      - Which call deletes a portlet from the current user's layout?
      instructions:
      - text: Remove portlet {portletId} from my personal layout.
        slots:
          portletId: path.portletId
      - text: Drop {portletId} from my own portlet menu.
        slots:
          portletId: path.portletId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/portlet/portletId/{portletId}/roleId/{roleId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a portlet from a role's layout
      effect: destructive
      questions:
      - How do I take a portlet away from everyone in a particular role?
      - Can I hide a portlet for one role while other roles keep it?
      instructions:
      - text: Remove portlet {portletId} from role {roleId}.
        slots:
          portletId: path.portletId
          roleId: path.roleId
      - text: Revoke access to {portletId} for users in role {roleId}.
        slots:
          portletId: path.portletId
          roleId: path.roleId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/portlet/{portletId}/_doesuserhaveaccess'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if I can access a portlet
      effect: read
      questions:
      - Does the current user have access to a given portlet?
      - Can I test portlet permissions before showing a menu link?
      instructions:
      - text: Check whether I have access to portlet {portletId}.
        slots:
          portletId: path.portletId
      - text: Verify the current user can open {portletId}.
        slots:
          portletId: path.portletId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/portlet/{portletId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a portlet by ID
      effect: read
      questions:
      - What is configured on a specific portlet?
      - Can I look up a portlet's definition by its ID?
      instructions:
      - text: Get portlet {portletId}.
        slots:
          portletId: path.portletId
      - text: Show the configuration of portlet {portletId}.
        slots:
          portletId: path.portletId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/portlet/_actionurl/{contentTypeVariable}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the create-content URL for a content type
      effect: read
      questions:
      - What admin URL opens the editor to create new content of a given type?
      - Can I get the create-content link in a specific language?
      instructions:
      - text: Get the create-content URL for content type {contentTypeVariable}.
        slots:
          contentTypeVariable: path.contentTypeVariable
      - text: Build the new-content editor link for {contentTypeVariable} in language {language_id}.
        slots:
          contentTypeVariable: path.contentTypeVariable
          language_id: query.language_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/portlet/custom'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a custom content portlet
      effect: write
      questions:
      - Can I change which content types an existing custom portlet shows?
      - How do I rename a custom portlet I already made?
      instructions:
      - text: Update custom portlet {portletId} to show content types {contentTypes}.
        slots:
          portletId: requestBody.portletId
          contentTypes: requestBody.contentTypes
      - text: Rename existing custom portlet {portletId} to {portletName}.
        slots:
          portletId: requestBody.portletId
          portletName: requestBody.portletName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/portlet/custom'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom content portlet
      effect: write
      questions:
      - How do I create a custom portlet that lists only certain content types?
      - Can a new custom portlet default to a list or card view?
      instructions:
      - text: Create a custom portlet {portletId} named {portletName} for content types {contentTypes}.
        slots:
          portletId: requestBody.portletId
          portletName: requestBody.portletName
          contentTypes: requestBody.contentTypes
      - text: Make a new content portlet {portletName} covering base types {baseTypes} in view mode {dataViewMode}.
        slots:
          portletName: requestBody.portletName
          baseTypes: requestBody.baseTypes
          dataViewMode: requestBody.dataViewMode
      method: generated
      generated: '2026-09-26'