# 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 Containers API
  version: 1.0.0
extends: openapi/dotcms-containers-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: 21
- target: $.paths['/api/v1/containers/_archive'].put
  update:
    x-apievangelist-phrasing:
      intent: Archive a container
      effect: write
      questions:
      - How do I archive a single container I no longer use?
      - What permission do I need to archive a container?
      instructions:
      - text: Archive container {containerId}.
        slots:
          containerId: query.containerId
      - text: Move container {containerId} to the archive.
        slots:
          containerId: query.containerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/_bulkarchive'].put
  update:
    x-apievangelist-phrasing:
      intent: Archive several containers at once
      effect: write
      questions:
      - Can I archive a whole list of containers in one request?
      - Will a bulk container archive tell me which ones failed?
      instructions:
      - text: Archive these containers in bulk and report which ones failed.
      - text: Bulk-archive the list of container identifiers I give you.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/_bulkdelete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete several containers at once
      effect: destructive
      questions:
      - Can I permanently delete a batch of containers together?
      - Does a bulk container delete report per-container failures?
      instructions:
      - text: Bulk-delete the containers in my list.
      - text: Permanently remove these container identifiers in one go and summarize failures.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/_bulkpublish'].put
  update:
    x-apievangelist-phrasing:
      intent: Publish several containers at once
      effect: write
      questions:
      - Is there a way to publish many containers in a single call?
      - What happens if I lack publish rights on some containers in a batch?
      instructions:
      - text: Bulk-publish the containers in my list.
      - text: Make these container identifiers live together and tell me which failed.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/_bulkunarchive'].put
  update:
    x-apievangelist-phrasing:
      intent: Unarchive several containers at once
      effect: write
      questions:
      - Can I restore a batch of archived containers in one request?
      - Which containers failed when I unarchived a list of them?
      instructions:
      - text: Bulk-unarchive the containers in my list.
      - text: Restore these archived container identifiers together.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/_bulkunpublish'].put
  update:
    x-apievangelist-phrasing:
      intent: Unpublish several containers at once
      effect: write
      questions:
      - Can I take a set of containers offline together?
      - Does bulk unpublishing containers return a success and failure summary?
      instructions:
      - text: Bulk-unpublish the containers in my list.
      - text: Take these container identifiers out of live status in one call.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/{containerId}/content/{contentletId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Render a contentlet inside a container
      effect: read
      questions:
      - How do I get the HTML a contentlet renders as inside a specific container?
      - Can I preview a piece of content with a container's markup applied?
      instructions:
      - text: Render contentlet {contentletId} inside container {containerId}.
        slots:
          contentletId: path.contentletId
          containerId: path.containerId
      - text: Get the HTML for content {contentletId} in container {containerId} on page {pageInode}.
        slots:
          contentletId: path.contentletId
          containerId: path.containerId
          pageInode: query.pageInode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/content/{contentletId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Render content in a file-based container
      effect: read
      questions:
      - How do I render content inside a file-asset container whose ID is a path?
      - Can I pass the container ID as a query parameter when rendering a contentlet?
      instructions:
      - text: Render contentlet {contentletId} in file container {containerId} passed as a query parameter.
        slots:
          contentletId: path.contentletId
          containerId: query.containerId
      - text: Get HTML for content {contentletId} using the container at path {containerId}.
        slots:
          contentletId: path.contentletId
          containerId: query.containerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/{containerId}/form/{formId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Render a form inside a container
      effect: read
      questions:
      - How can I display a form with a container's styling and layout?
      - What HTML does a form produce when placed in a given container?
      instructions:
      - text: Render form {formId} inside container {containerId}.
        slots:
          formId: path.formId
          containerId: path.containerId
      - text: Get the container-styled HTML for form {formId} in container {containerId}.
        slots:
          formId: path.formId
          containerId: path.containerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/form/{formId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Render a form in a file-based container
      effect: read
      questions:
      - Can I render a form inside a file-asset container addressed by its path?
      - How do I get form HTML when the container ID goes in the query string?
      instructions:
      - text: Render form {formId} in the file container at {containerId}.
        slots:
          formId: path.formId
          containerId: query.containerId
      - text: Get HTML for form {formId}, passing container path {containerId} as a query parameter.
        slots:
          formId: path.formId
          containerId: query.containerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/{id}/_copy'].post
  update:
    x-apievangelist-phrasing:
      intent: Copy a container to the current site
      effect: write
      questions:
      - How do I duplicate a container onto the site I'm working in?
      - Can I clone an existing container instead of building a new one?
      instructions:
      - text: Copy container {id} to the current host.
        slots:
          id: path.id
      - text: Duplicate container {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers'].get
  update:
    x-apievangelist-phrasing:
      intent: List containers
      effect: read
      questions:
      - Which containers exist on my site?
      - Can I filter the container list by name or content type?
      - How do I include archived or system containers in a listing?
      instructions:
      - text: List my containers.
      - text: List containers matching {filter} on site {host}.
        slots:
          filter: query.filter
          host: query.host
      - text: Show containers that allow content type {content_type}, {per_page} per page.
        slots:
          content_type: query.content_type
          per_page: query.per_page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing container
      effect: write
      questions:
      - How do I change the code or max contentlets of a container that already exists?
      - Can I edit a container's working version without publishing it?
      instructions:
      - text: Update container {identifier} with title {title}.
        slots:
          identifier: requestBody.identifier
          title: requestBody.title
      - text: Change existing container {identifier} titled {title} to allow {maxContentlets} contentlets.
        slots:
          identifier: requestBody.identifier
          title: requestBody.title
          maxContentlets: requestBody.maxContentlets
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new container
      effect: write
      questions:
      - How do I create a new container in dotCMS?
      - Is a newly created container published straight away?
      instructions:
      - text: Create a new container titled {title}.
        slots:
          title: requestBody.title
      - text: Create container {title} on site {hostId} holding up to {maxContentlets} items.
        slots:
          title: requestBody.title
          hostId: requestBody.hostId
          maxContentlets: requestBody.maxContentlets
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a container
      effect: destructive
      questions:
      - How do I permanently delete one container?
      - Is deleting a single container reversible?
      instructions:
      - text: Delete container {containerId}.
        slots:
          containerId: query.containerId
      - text: Permanently remove container {containerId}.
        slots:
          containerId: query.containerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/live'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the live version of a container
      effect: read
      questions:
      - What does the published version of this container look like?
      - Can I see the live container along with its content types?
      instructions:
      - text: Get the live version of container {containerId}.
        slots:
          containerId: query.containerId
      - text: Show published container {containerId} including its content types.
        slots:
          containerId: query.containerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/working'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the working draft of a container
      effect: read
      questions:
      - How do I view the unpublished working copy of a container?
      - Is there a way to see a container's draft with its content type details?
      instructions:
      - text: Get the working version of container {containerId}.
        slots:
          containerId: query.containerId
      - text: Show draft container {containerId} with content types.
        slots:
          containerId: query.containerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/_publish'].put
  update:
    x-apievangelist-phrasing:
      intent: Publish a container
      effect: write
      questions:
      - How do I make a single container live?
      - What permission is needed to publish a container?
      instructions:
      - text: Publish container {containerId}.
        slots:
          containerId: query.containerId
      - text: Make container {containerId} live.
        slots:
          containerId: query.containerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/delete/{containerId}/content/{contentletId}/uid/{uid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove content from a container slot
      effect: destructive
      questions:
      - How do I take a contentlet out of a container on a page?
      - Can I remove content from a container at a specific position?
      instructions:
      - text: Remove contentlet {contentletId} from container {containerId} at uid {uid}.
        slots:
          contentletId: path.contentletId
          containerId: path.containerId
          uid: path.uid
      - text: Pull content {contentletId} out of container {containerId} instance {uid} at order {order}.
        slots:
          contentletId: path.contentletId
          containerId: path.containerId
          uid: path.uid
          order: query.order
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/_unarchive'].put
  update:
    x-apievangelist-phrasing:
      intent: Unarchive a container
      effect: write
      questions:
      - How do I restore one archived container?
      - Can an archived container be brought back to active?
      instructions:
      - text: Unarchive container {containerId}.
        slots:
          containerId: query.containerId
      - text: Restore archived container {containerId}.
        slots:
          containerId: query.containerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/containers/_unpublish'].put
  update:
    x-apievangelist-phrasing:
      intent: Unpublish a container
      effect: write
      questions:
      - How do I take one container out of live status?
      - What permission do I need to unpublish a container?
      instructions:
      - text: Unpublish container {containerId}.
        slots:
          containerId: query.containerId
      - text: Take container {containerId} offline.
        slots:
          containerId: query.containerId
      method: generated
      generated: '2026-09-26'