# 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 Content API
  version: 1.0.0
extends: openapi/dotcms-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: 32
- target: $.paths['/api/v1/contentrelationships/{params}'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch content with relationships (deprecated)
      effect: read
      questions:
      - Is there still an old endpoint that returns a contentlet together with its relationships?
      - What replaced the deprecated contentrelationships lookup in dotCMS?
      instructions:
      - text: Use the deprecated content relationships endpoint with parameters {params}.
        slots:
          params: path.params
      - text: Pull content plus its related items through the legacy relationships lookup using {params}.
        slots:
          params: path.params
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_canlock/{inodeOrIdentifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether I can lock a contentlet
      effect: read
      questions:
      - Am I allowed to lock this piece of content before I start editing it?
      - Can I check if a contentlet is lockable in a specific language?
      instructions:
      - text: Check whether I can lock contentlet {inodeOrIdentifier}.
        slots:
          inodeOrIdentifier: path.inodeOrIdentifier
      - text: See if contentlet {inodeOrIdentifier} is lockable by me in language {language}.
        slots:
          inodeOrIdentifier: path.inodeOrIdentifier
          language: query.language
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/{identifier}/languages'].get
  update:
    x-apievangelist-phrasing:
      intent: See which languages a contentlet exists in
      effect: read
      questions:
      - Which languages does this piece of content already have a version in?
      - How can I tell which translations are missing for a contentlet?
      instructions:
      - text: List the languages available for contentlet {identifier} and mark which have versions.
        slots:
          identifier: path.identifier
      - text: Show me which translations exist for content {identifier}.
        slots:
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/{identifier}/references/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count references to a contentlet
      effect: read
      questions:
      - How many places reference this contentlet?
      - Is a piece of content used anywhere before I delete it, just as a number?
      instructions:
      - text: Count how many references point to contentlet {identifier}.
        slots:
          identifier: path.identifier
      - text: Give me just the reference total for content {identifier}.
        slots:
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/{inodeOrIdentifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a contentlet
      effect: read
      questions:
      - How do I fetch a single contentlet by its identifier or inode in dotCMS?
      - Can I load a contentlet with its related content resolved to a certain depth?
      - Can I get a specific variant of a piece of content?
      instructions:
      - text: Get contentlet {inodeOrIdentifier}.
        slots:
          inodeOrIdentifier: path.inodeOrIdentifier
      - text: Fetch contentlet {inodeOrIdentifier} in language {language} with relationships at depth {depth}.
        slots:
          inodeOrIdentifier: path.inodeOrIdentifier
          language: query.language
          depth: query.depth
      - text: Load the {variantName} variant of contentlet {inodeOrIdentifier}.
        slots:
          variantName: query.variantName
          inodeOrIdentifier: path.inodeOrIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/{inodeOrIdentifier}/references'].get
  update:
    x-apievangelist-phrasing:
      intent: List pages and containers using a contentlet
      effect: read
      questions:
      - Which pages, containers and personas use this contentlet?
      - Where exactly is a piece of content placed across my site?
      instructions:
      - text: List every page, container and persona that references contentlet {inodeOrIdentifier}.
        slots:
          inodeOrIdentifier: path.inodeOrIdentifier
      - text: Show where content {inodeOrIdentifier} is used in language {language}.
        slots:
          inodeOrIdentifier: path.inodeOrIdentifier
          language: query.language
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/{identifier}/push/history'].get
  update:
    x-apievangelist-phrasing:
      intent: View a contentlet's push publishing history
      effect: read
      questions:
      - When was this contentlet last push-published to another environment?
      - Can I page through the push history of a piece of content?
      instructions:
      - text: Show the push publishing history for contentlet {identifier}.
        slots:
          identifier: path.identifier
      - text: List the last {limit} pushes of content {identifier}.
        slots:
          limit: query.limit
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_lock/{inodeOrIdentifier}'].put
  update:
    x-apievangelist-phrasing:
      intent: Lock a contentlet for editing
      effect: write
      questions:
      - How do I lock a contentlet so nobody else edits it while I work?
      - Can I lock just one language version of a piece of content?
      instructions:
      - text: Lock contentlet {inodeOrIdentifier} for me.
        slots:
          inodeOrIdentifier: path.inodeOrIdentifier
      - text: Lock the {language} version of content {inodeOrIdentifier}.
        slots:
          language: query.language
          inodeOrIdentifier: path.inodeOrIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/related'].post
  update:
    x-apievangelist-phrasing:
      intent: Pull content related through a relationship field
      effect: read
      questions:
      - How can I get the items linked to a contentlet through a relationship field?
      - Can I filter and sort the related content returned for a relationship field?
      instructions:
      - text: Pull content related to {identifier} through field {fieldVariable}, {limit} at a time from offset {offset}, ordered by {orderBy}.
        slots:
          identifier: requestBody.identifier
          fieldVariable: requestBody.fieldVariable
          limit: requestBody.limit
          offset: requestBody.offset
          orderBy: requestBody.orderBy
      - text: Get items related to {identifier} via {fieldVariable} matching {condition}, limit {limit}, offset {offset}, sorted by {orderBy}.
        slots:
          identifier: requestBody.identifier
          fieldVariable: requestBody.fieldVariable
          condition: requestBody.condition
          limit: requestBody.limit
          offset: requestBody.offset
          orderBy: requestBody.orderBy
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_refresh/{identifierOrInode}'].put
  update:
    x-apievangelist-phrasing:
      intent: Reindex and clear cache for one contentlet
      effect: write
      questions:
      - My content change isn't showing up in search results — can I force one contentlet to refresh?
      - What's the way to reindex a single contentlet and clear its cache?
      instructions:
      - text: Refresh contentlet {identifierOrInode} in the index and cache.
        slots:
          identifierOrInode: path.identifierOrInode
      - text: Reindex the {language} version of content {identifierOrInode}.
        slots:
          language: query.language
          identifierOrInode: path.identifierOrInode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_draft'].put
  update:
    x-apievangelist-phrasing:
      intent: Save a content draft without workflow
      effect: write
      questions:
      - Can I save work in progress on a contentlet without triggering a workflow?
      - How do I store a draft version of content without publishing it?
      instructions:
      - text: 'Save this contentlet as a draft: {contentlet}.'
        slots:
          contentlet: requestBody.contentlet
      - text: Save a draft of content {identifier} with these values {contentlet}.
        slots:
          identifier: query.identifier
          contentlet: requestBody.contentlet
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search content by searchable fields
      effect: read
      questions:
      - Can I search content without writing a Lucene query myself?
      - How do I include archived or locked content in a simple content search?
      - Which content matches a keyword across my content types' searchable fields?
      instructions:
      - text: Search content for {globalSearch}.
        slots:
          globalSearch: requestBody.globalSearch
      - text: Find content matching {globalSearch}, including archived items, {perPage} per page.
        slots:
          globalSearch: requestBody.globalSearch
          perPage: requestBody.perPage
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_unlock/{inodeOrIdentifier}'].put
  update:
    x-apievangelist-phrasing:
      intent: Unlock a contentlet
      effect: write
      questions:
      - How do I release my lock on a contentlet when I'm done editing?
      - Can I unlock one language version of a locked piece of content?
      instructions:
      - text: Unlock contentlet {inodeOrIdentifier}.
        slots:
          inodeOrIdentifier: path.inodeOrIdentifier
      - text: Release the lock on the {language} version of content {inodeOrIdentifier}.
        slots:
          language: query.language
          inodeOrIdentifier: path.inodeOrIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search content with a Lucene query
      effect: read
      questions:
      - How do I run a raw Lucene query against dotCMS content?
      - Can a Lucene content search return related content and rendered output?
      - What's the way to sort and paginate Lucene search results?
      instructions:
      - text: Run the Lucene query {query} against content.
        slots:
          query: requestBody.query
      - text: Search content with Lucene {query}, sorted by {sort}, limit {limit}.
        slots:
          query: requestBody.query
          sort: requestBody.sort
          limit: requestBody.limit
      - text: Lucene-search {query} in language {languageId} with relationships to depth {depth}.
        slots:
          query: requestBody.query
          languageId: requestBody.languageId
          depth: requestBody.depth
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/versions/{inode}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one content version by inode
      effect: read
      questions:
      - How can I open a specific past version of a contentlet by its inode?
      - What did this exact content version look like?
      instructions:
      - text: Get content version {inode}.
        slots:
          inode: path.inode
      - text: Show me the contentlet version stored under inode {inode}.
        slots:
          inode: path.inode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List versions of content
      effect: read
      questions:
      - Where can I see all the versions of a contentlet?
      - Can I group content versions by language?
      instructions:
      - text: List versions of content {identifier}.
        slots:
          identifier: query.identifier
      - text: Get versions for inodes {inodes}, grouped by language.
        slots:
          inodes: query.inodes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/versions/id/{identifier}/history'].get
  update:
    x-apievangelist-phrasing:
      intent: Show a contentlet's edit history
      effect: read
      questions:
      - Who edited this contentlet and when, like the History tab shows?
      - Can I include old versions when viewing a content item's history?
      instructions:
      - text: Show the edit history of contentlet {identifier} in language {languageId}.
        slots:
          identifier: path.identifier
          languageId: query.languageId
      - text: Get the last {limit} history entries for content {identifier} in language {languageId}.
        slots:
          limit: query.limit
          identifier: path.identifier
          languageId: query.languageId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/resourcelinks/field/{field}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the resource link for one binary field
      effect: read
      questions:
      - How do I get the download link for one file field on a contentlet?
      - What's the public URL of a specific binary field's file?
      instructions:
      - text: Get the resource link for field {field} on contentlet {identifier}.
        slots:
          field: path.field
          identifier: query.identifier
      - text: Give me the URL of the {field} file on content inode {inode}.
        slots:
          field: path.field
          inode: query.inode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/resourcelinks'].get
  update:
    x-apievangelist-phrasing:
      intent: Get resource links for all binary fields
      effect: read
      questions:
      - Can I get the links to every file attached to a contentlet at once?
      - Which binary files does this piece of content carry, and what are their URLs?
      instructions:
      - text: List resource links for all binary fields of contentlet {identifier}.
        slots:
          identifier: query.identifier
      - text: Get every file link on content inode {inode}.
        slots:
          inode: query.inode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_bulkrefresh'].post
  update:
    x-apievangelist-phrasing:
      intent: Reindex a batch of contentlets
      effect: write
      questions:
      - Can I reindex many contentlets at once, including all their versions?
      - Does a bulk reindex finish immediately or run as a background job?
      instructions:
      - text: Reindex contentlets {contentletIds}.
        slots:
          contentletIds: requestBody.contentletIds
      - text: Bulk refresh {contentletIds} and include their dependencies.
        slots:
          contentletIds: requestBody.contentletIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_import/abandoned'].get
  update:
    x-apievangelist-phrasing:
      intent: List abandoned content import jobs
      effect: read
      questions:
      - Which content imports were abandoned?
      - Are there import jobs stuck in the ABANDONED state?
      instructions:
      - text: List abandoned content import jobs.
      - text: Show page {page} of abandoned imports, {pageSize} per page.
        slots:
          page: query.page
          pageSize: query.pageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_import/active'].get
  update:
    x-apievangelist-phrasing:
      intent: List content imports in progress
      effect: read
      questions:
      - Which CSV imports are running or waiting right now?
      - Can I see imports that are new, processing or queued?
      instructions:
      - text: List active content import jobs.
      - text: Show {pageSize} running imports from page {page}.
        slots:
          pageSize: query.pageSize
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_import/{jobId}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a content import job
      effect: destructive
      questions:
      - How do I stop a CSV content import that's already running?
      - Is cancelling an import instant, or does it take a while?
      instructions:
      - text: Cancel content import job {jobId}.
        slots:
          jobId: path.jobId
      - text: Stop import {jobId}.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_import/canceled'].get
  update:
    x-apievangelist-phrasing:
      intent: List canceled content import jobs
      effect: read
      questions:
      - Which content imports were canceled?
      - Can I page through imports someone stopped?
      instructions:
      - text: List canceled content import jobs.
      - text: Show page {page} of canceled imports.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_import/completed'].get
  update:
    x-apievangelist-phrasing:
      intent: List completed content import jobs
      effect: read
      questions:
      - Which content imports have finished, whatever their outcome?
      - What imports reached the COMPLETED state?
      instructions:
      - text: List completed content import jobs.
      - text: Show {pageSize} finished imports per page.
        slots:
          pageSize: query.pageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_import/failed'].get
  update:
    x-apievangelist-phrasing:
      intent: List failed content import jobs
      effect: read
      questions:
      - Which of my CSV imports failed?
      - Can I see only the imports that ended in error?
      instructions:
      - text: List failed content import jobs.
      - text: Show page {page} of failed imports.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_import/{jobId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a content import job's status
      effect: read
      questions:
      - What's the current status of my content import?
      - How far along is a specific CSV import job?
      instructions:
      - text: Get the status of import job {jobId}.
        slots:
          jobId: path.jobId
      - text: Check on content import {jobId}.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_import'].get
  update:
    x-apievangelist-phrasing:
      intent: List all content import jobs
      effect: read
      questions:
      - Can I list every content import job regardless of its state?
      - What imports have been run on this instance?
      instructions:
      - text: List all content import jobs.
      - text: Show page {page} of all imports, {pageSize} per page.
        slots:
          page: query.page
          pageSize: query.pageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_import'].post
  update:
    x-apievangelist-phrasing:
      intent: Import content from a CSV file
      effect: write
      questions:
      - How do I bulk-load content into dotCMS from a CSV?
      - Can I queue a CSV import for a content type with import settings?
      instructions:
      - text: Import {file} as content using settings {form}.
        slots:
          file: requestBody.file
          form: requestBody.form
      - text: Start a content import job from CSV {file} with parameters {form}.
        slots:
          file: requestBody.file
          form: requestBody.form
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_import/{jobId}/monitor'].get
  update:
    x-apievangelist-phrasing:
      intent: Stream live progress of an import job
      effect: read
      questions:
      - Can I watch a content import's progress in real time?
      - Is there a server-sent events stream for import job updates?
      instructions:
      - text: Stream live progress for import job {jobId}.
        slots:
          jobId: path.jobId
      - text: Monitor import {jobId} until it finishes.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_import/successful'].get
  update:
    x-apievangelist-phrasing:
      intent: List successful content import jobs
      effect: read
      questions:
      - Which content imports completed successfully?
      - Can I see only the imports that succeeded, not the failed completions?
      instructions:
      - text: List successful content import jobs.
      - text: Show page {page} of successful imports.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/content/_import/_validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Dry-run a CSV content import
      effect: read
      questions:
      - Can I check a CSV against a content type before actually importing it?
      - Is there a preview mode that validates an import without creating content?
      instructions:
      - text: Validate CSV {file} with settings {form} without importing.
        slots:
          file: requestBody.file
          form: requestBody.form
      - text: Preview the import of {file} using {form}.
        slots:
          file: requestBody.file
          form: requestBody.form
      method: generated
      generated: '2026-09-26'