# 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 Site API
  version: 1.0.0
extends: openapi/dotcms-site-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: 20
- target: $.paths['/api/v1/site/{siteId}/_archive'].put
  update:
    x-apievangelist-phrasing:
      intent: Archive a site
      effect: write
      questions:
      - How do I archive a site I no longer use in dotCMS?
      - Can the default site be archived?
      instructions:
      - text: Archive site {siteId}.
        slots:
          siteId: path.siteId
      - text: Unlock and archive the site with host ID {siteId}.
        slots:
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/_copy'].put
  update:
    x-apievangelist-phrasing:
      intent: Create a new site by copying another
      effect: write
      questions:
      - Can I clone an existing site with its templates, containers and folders?
      - Which parts of a site can be copied, such as content types, links or site variables?
      instructions:
      - text: Copy everything from site {copyFromSiteId} into a new site {site}.
        slots:
          copyFromSiteId: requestBody.copyFromSiteId
          site: requestBody.site
      - text: Clone site {copyFromSiteId}, copying only templates, containers and folders.
        slots:
          copyFromSiteId: requestBody.copyFromSiteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site'].get
  update:
    x-apievangelist-phrasing:
      intent: List sites I can access
      effect: read
      questions:
      - Which sites do I have access to?
      - Can I list only archived sites, or only live ones?
      instructions:
      - text: List the sites whose name matches {filter}.
        slots:
          filter: query.filter
      - text: Show page {page} of my sites, {per_page} per page, including system sites.
        slots:
          page: query.page
          per_page: query.per_page
      - text: List all archived sites.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a site's properties
      effect: write
      questions:
      - How do I change an existing site's aliases or SEO keywords?
      - Can I update a site's description and Google Analytics code?
      instructions:
      - text: Update site {id} with hostname {siteName} and aliases {aliases}.
        slots:
          id: query.id
          siteName: requestBody.siteName
          aliases: requestBody.aliases
      - text: Set the description of site {id} ({siteName}) to {description}.
        slots:
          id: query.id
          siteName: requestBody.siteName
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new site
      effect: write
      questions:
      - How do I add a new site with its own hostname?
      - Can I set aliases, tag storage and site variables when creating a site?
      instructions:
      - text: Create a new site named {siteName}.
        slots:
          siteName: requestBody.siteName
      - text: Create site {siteName} with aliases {aliases} and keywords {keywords}.
        slots:
          siteName: requestBody.siteName
          aliases: requestBody.aliases
          keywords: requestBody.keywords
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/currentSite'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the site selected in my session
      effect: read
      questions:
      - Which site am I currently working in?
      - What site does the site selector show for my session right now?
      instructions:
      - text: Show the site currently selected in my session.
      - text: Tell me which site I'm working in right now.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/defaultSite'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the system default site
      effect: read
      questions:
      - Which site is marked as the default in dotCMS?
      - What is the system's default site?
      instructions:
      - text: Show me the default site.
      - text: Get the site flagged as the system default.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/{siteId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a site's details
      effect: read
      questions:
      - How do I get the full details of a site from its identifier?
      - What settings does a particular site have?
      instructions:
      - text: Get the details of site {siteId}.
        slots:
          siteId: path.siteId
      - text: Show everything configured on host ID {siteId}.
        slots:
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/{siteId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a site
      effect: destructive
      questions:
      - How do I permanently delete a site?
      - Why can't I delete the default site?
      instructions:
      - text: Delete site {siteId}.
        slots:
          siteId: path.siteId
      - text: Permanently remove the site with host ID {siteId}.
        slots:
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/thumbnails'].get
  update:
    x-apievangelist-phrasing:
      intent: List thumbnails for all sites
      effect: read
      questions:
      - Which of my sites have a thumbnail image set?
      - Can I get every site's thumbnail and tag storage in one list?
      instructions:
      - text: List all sites with their thumbnail information.
      - text: Show which sites have a thumbnail.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/_byname'].post
  update:
    x-apievangelist-phrasing:
      intent: Find a site by hostname
      effect: read
      questions:
      - How do I look up a site by its hostname?
      - Can I find a site whose hostname has special characters?
      instructions:
      - text: Find the site with hostname {siteName}.
        slots:
          siteName: requestBody.siteName
      - text: Look up site {siteName} by name.
        slots:
          siteName: requestBody.siteName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/{siteId}/setup_progress'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a site copy's setup progress
      effect: read
      questions:
      - How far along is the asset copy for a site I just cloned?
      - Is the background copy job for my new site finished?
      instructions:
      - text: Show the setup progress of site {siteId}.
        slots:
          siteId: path.siteId
      - text: Check whether assets have finished copying into site {siteId}.
        slots:
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/variable/{siteId}'].get
  update:
    x-apievangelist-phrasing:
      intent: List a site's variables
      effect: read
      questions:
      - What site variables are defined on a site?
      - Who last changed a site's variables?
      instructions:
      - text: List the site variables for site {siteId}.
        slots:
          siteId: path.siteId
      - text: Show every variable key and value on site {siteId}.
        slots:
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/{siteId}/_makedefault'].put
  update:
    x-apievangelist-phrasing:
      intent: Make a site the default
      effect: write
      questions:
      - How do I change which site is the system default?
      - Can I promote another site to default before deleting the current one?
      instructions:
      - text: Make site {siteId} the default site.
        slots:
          siteId: path.siteId
      - text: Mark host {siteId} as the system default.
        slots:
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/{siteId}/_publish'].put
  update:
    x-apievangelist-phrasing:
      intent: Publish a site
      effect: write
      questions:
      - How do I make a site live?
      - Can I bring an unpublished site back online?
      instructions:
      - text: Publish site {siteId}.
        slots:
          siteId: path.siteId
      - text: Make site {siteId} live and accessible.
        slots:
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/variable'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update a site variable
      effect: write
      questions:
      - How do I add a variable to a site?
      - Will saving a site variable with an existing key overwrite it?
      instructions:
      - text: Set site variable {key} to {value} on site {siteId}.
        slots:
          key: requestBody.key
          value: requestBody.value
          siteId: requestBody.siteId
      - text: Create a site variable named {name} with key {key} on site {siteId}.
        slots:
          name: requestBody.name
          key: requestBody.key
          siteId: requestBody.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/switch'].put
  update:
    x-apievangelist-phrasing:
      intent: Switch my session to my default site
      effect: write
      questions:
      - How do I switch back to my default site?
      - Can I reset my active site to the default in one step?
      instructions:
      - text: Switch my active site back to my default site.
      - text: Reset the site I'm working in to my default.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/switch/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Switch my session to a specific site
      effect: write
      questions:
      - How do I change the site I'm currently working in?
      - Can an agent switch my active site for me?
      instructions:
      - text: Switch my active site to {id}.
        slots:
          id: path.id
      - text: Start working in site {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/{siteId}/_unarchive'].put
  update:
    x-apievangelist-phrasing:
      intent: Restore an archived site
      effect: write
      questions:
      - How do I bring back a site I archived?
      - Can an archived site be made active again?
      instructions:
      - text: Unarchive site {siteId}.
        slots:
          siteId: path.siteId
      - text: Restore archived site {siteId} to active.
        slots:
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/site/{siteId}/_unpublish'].put
  update:
    x-apievangelist-phrasing:
      intent: Unpublish a site
      effect: write
      questions:
      - How do I take a site offline without deleting it?
      - Can I remove a site from live status temporarily?
      instructions:
      - text: Unpublish site {siteId}.
        slots:
          siteId: path.siteId
      - text: Take site {siteId} out of live status.
        slots:
          siteId: path.siteId
      method: generated
      generated: '2026-09-26'