# 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 AI API
  version: 1.0.0
extends: openapi/dotcms-ai-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: 23
- target: $.paths['/api/v1/ai/providers'].get
  update:
    x-apievangelist-phrasing:
      intent: List dotAI providers and their config fields
      effect: read
      questions:
      - Which AI providers can dotAI use and do they support chat, embeddings or images?
      - What configuration fields does each dotAI provider capability require?
      instructions:
      - text: List every registered dotAI provider with the capabilities it supports.
      - text: Show the providerConfig fields each AI provider needs for chat, embeddings and images.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/providers/test/{capability}'].post
  update:
    x-apievangelist-phrasing:
      intent: Test a dotAI provider connection
      effect: read
      questions:
      - How can I check that my AI provider credentials actually work before saving them?
      - Does the connection test make a real request to the provider for embeddings or images?
      instructions:
      - text: Test the AI provider connection for the {capability} capability.
        slots:
          capability: path.capability
      - text: Verify the {capability} provider config works for site {siteId} using the stored credentials.
        slots:
          capability: path.capability
          siteId: query.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/completions/config'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the AI service configuration
      effect: read
      questions:
      - What AI configuration is currently set for my site?
      - Can I read the system-wide AI settings using SYSTEM_HOST instead of a site id?
      instructions:
      - text: Show the current AI service configuration.
      - text: Get the AI configuration saved for site {siteId}.
        slots:
          siteId: query.siteId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/completions/config'].put
  update:
    x-apievangelist-phrasing:
      intent: Save AI provider configuration for a site
      effect: write
      questions:
      - How do I save new AI provider settings for a site?
      - Will saving the AI config overwrite credentials that show as masked asterisks?
      instructions:
      - text: Save this AI provider configuration for site {siteId}.
        slots:
          siteId: query.siteId
      - text: Update the AI provider settings for the current host.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/completions/rawPrompt'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a raw prompt to the AI without content lookup
      effect: read
      questions:
      - Can I send a prompt straight to the model without dotCMS adding content context?
      - Does the raw prompt endpoint support streaming responses?
      instructions:
      - text: Send the raw prompt {prompt} directly to the AI model with no content preprocessing.
        slots:
          prompt: requestBody.prompt
      - text: Run raw prompt {prompt} on model {model} at temperature {temperature}.
        slots:
          prompt: requestBody.prompt
          model: requestBody.model
          temperature: requestBody.temperature
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/completions'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate an AI answer grounded in site content
      effect: read
      questions:
      - How do I get an AI summary built from content in my dotCMS embeddings index?
      - Can I restrict an AI completion to a specific content type and index?
      instructions:
      - text: Summarize what our content says about {prompt} using the {indexName} index.
        slots:
          prompt: requestBody.prompt
          indexName: requestBody.indexName
      - text: Answer {prompt} from {contentType} content only, streaming the completion.
        slots:
          prompt: requestBody.prompt
          contentType: requestBody.contentType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/embeddings/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count embeddings matching query-string filters
      effect: read
      questions:
      - How many embeddings exist for a given content type or site?
      - Can I count embeddings for one contentlet by identifier or inode?
      instructions:
      - text: Count the embeddings for content type {contentType} on site {site}.
        slots:
          contentType: query.contentType
          site: query.site
      - text: Tell me how many embeddings contentlet {identifier} has in index {indexName}.
        slots:
          identifier: query.identifier
          indexName: query.indexName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/embeddings/count'].post
  update:
    x-apievangelist-phrasing:
      intent: Count embeddings using a JSON filter body
      effect: read
      questions:
      - Can I count embeddings by posting a JSON search form instead of query parameters?
      - How many embeddings would match a posted filter on index and field?
      instructions:
      - text: Post a filter and count embeddings in index {indexName} for field {fieldVar}.
        slots:
          indexName: requestBody.indexName
          fieldVar: requestBody.fieldVar
      - text: Count embeddings via JSON body for content type {contentType} in language {language}.
        slots:
          contentType: requestBody.contentType
          language: requestBody.language
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/embeddings'].post
  update:
    x-apievangelist-phrasing:
      intent: Create embeddings for content matching a query
      effect: write
      questions:
      - How do I generate vector embeddings for content so dotAI can search it?
      - Can I choose which fields get embedded and which index they go into?
      instructions:
      - text: Build embeddings for content matching {query} into index {indexName}.
        slots:
          query: requestBody.query
          indexName: requestBody.indexName
      - text: Embed the fields {fields} of content returned by {query}.
        slots:
          fields: requestBody.fields
          query: requestBody.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/embeddings'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete stored content embeddings
      effect: destructive
      questions:
      - How do I remove embeddings I no longer want in the AI index?
      - Can I delete embeddings without dropping the whole embeddings database?
      instructions:
      - text: Delete the matching content embeddings.
      - text: Remove stored embeddings but keep the embeddings tables in place.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/embeddings/db'].delete
  update:
    x-apievangelist-phrasing:
      intent: Drop and recreate the embeddings tables
      effect: destructive
      questions:
      - How do I completely reset the dotAI embeddings database?
      - Is there a way to wipe all embeddings and rebuild the tables from scratch?
      instructions:
      - text: Drop and recreate the embeddings database tables.
      - text: Wipe all embeddings and reset the vector tables.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/embeddings/indexCount'].get
  update:
    x-apievangelist-phrasing:
      intent: Count embeddings per index
      effect: read
      questions:
      - Which embedding indexes exist and how many entries does each hold?
      - What is the size of each dotAI index?
      instructions:
      - text: Show the embeddings count for every index.
      - text: List the AI indexes with their sizes.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/embeddings/test'].get
  update:
    x-apievangelist-phrasing:
      intent: Test the embeddings endpoint
      effect: read
      questions:
      - Is the embeddings resource up and responding?
      - How can I smoke-test the embeddings service?
      instructions:
      - text: Ping the embeddings test endpoint.
      - text: Run the embeddings service health test.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/image/generate'].get
  update:
    x-apievangelist-phrasing:
      intent: Generate an image from a prompt in the URL
      effect: read
      questions:
      - Can I generate an AI image with a simple GET and a prompt query parameter?
      - What's the quickest way to create one image from a text prompt?
      instructions:
      - text: Generate an image via GET for the prompt {prompt}.
        slots:
          prompt: query.prompt
      - text: Make a quick AI picture of {prompt} using the query-string endpoint.
        slots:
          prompt: query.prompt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/image/generate'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate AI images with size and model options
      effect: write
      questions:
      - How do I generate several AI images at once in a specific size?
      - Can I pick the image model when generating images?
      instructions:
      - text: Generate {numberOfImages} images of {prompt} at size {size}.
        slots:
          numberOfImages: requestBody.numberOfImages
          prompt: requestBody.prompt
          size: requestBody.size
      - text: Create an image of {prompt} with model {model}.
        slots:
          prompt: requestBody.prompt
          model: requestBody.model
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/image/test'].get
  update:
    x-apievangelist-phrasing:
      intent: Test the image generation endpoint
      effect: read
      questions:
      - Is AI image generation reachable on my instance?
      - How do I smoke-test the image service?
      instructions:
      - text: Ping the image generation test endpoint.
      - text: Check that the AI image service responds.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/search/related'].get
  update:
    x-apievangelist-phrasing:
      intent: Find content related to a contentlet
      effect: read
      questions:
      - How can I find content semantically similar to a given contentlet?
      - Can I get related content by inode in a specific language?
      instructions:
      - text: Find content related to contentlet {identifier}.
        slots:
          identifier: query.identifier
      - text: Show related items for inode {inode} in index {indexName}.
        slots:
          inode: query.inode
          indexName: query.indexName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/search/related'].post
  update:
    x-apievangelist-phrasing:
      intent: Find related content using a posted JSON body
      effect: read
      questions:
      - Can I request related-content matches by posting JSON instead of query parameters?
      - Is there a POST variant for semantic related-content lookup?
      instructions:
      - text: Post a JSON request to find related content.
      - text: Look up semantically related content through the POST related endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Semantic search of content via query string
      effect: read
      questions:
      - How do I run a semantic AI search over my content with a simple GET?
      - Can I set a similarity threshold and result limit on AI search?
      instructions:
      - text: Semantically search content for {query}.
        slots:
          query: query.query
      - text: AI-search {query} on site {site} returning {searchLimit} results.
        slots:
          query: query.query
          site: query.site
          searchLimit: query.searchLimit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Semantic search of content via JSON body
      effect: read
      questions:
      - Can I post a full search form to the AI search endpoint?
      - Does the POST semantic search let me filter by content type and operator?
      instructions:
      - text: Post a semantic search for {prompt} in index {indexName}.
        slots:
          prompt: requestBody.prompt
          indexName: requestBody.indexName
      - text: Search {contentType} content for {prompt} using a JSON body with threshold {threshold}.
        slots:
          contentType: requestBody.contentType
          prompt: requestBody.prompt
          threshold: requestBody.threshold
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/search/test'].get
  update:
    x-apievangelist-phrasing:
      intent: Test the AI search endpoint
      effect: read
      questions:
      - Is the AI search service responding?
      - How do I smoke-test semantic search?
      instructions:
      - text: Ping the AI search test endpoint.
      - text: Check that AI search is up.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/text/generate'].get
  update:
    x-apievangelist-phrasing:
      intent: Generate text from a prompt in the URL
      effect: read
      questions:
      - Can I generate AI text with a GET request and a prompt parameter?
      - What's the simplest call to get generated text back?
      instructions:
      - text: Generate text via GET for the prompt {prompt}.
        slots:
          prompt: query.prompt
      - text: Write a quick blurb about {prompt} using the query-string text endpoint.
        slots:
          prompt: query.prompt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/ai/text/generate'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate text with model and length options
      effect: read
      questions:
      - How do I generate text with a set response length and temperature?
      - Can the text generator return a specific response format?
      instructions:
      - text: Generate text for {prompt} limited to {responseLengthTokens} tokens.
        slots:
          prompt: requestBody.prompt
          responseLengthTokens: requestBody.responseLengthTokens
      - text: Write copy about {prompt} in format {responseFormat}.
        slots:
          prompt: requestBody.prompt
          responseFormat: requestBody.responseFormat
      method: generated
      generated: '2026-09-26'