# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Dify Service Knowledge Bases API
  version: 1.0.0
extends: openapi/dify-knowledge-bases-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: 6
- target: $.paths['/datasets'].get
  update:
    x-apievangelist-phrasing:
      intent: List knowledge bases in the workspace
      effect: read
      questions:
      - Which knowledge bases exist in my Dify workspace?
      - Can I filter my knowledge bases by tag or by name?
      instructions:
      - text: List all my knowledge bases.
      - text: Find knowledge bases named like {keyword} tagged {tag_ids}.
        slots:
          keyword: query.keyword
          tag_ids: query.tag_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an empty knowledge base
      effect: write
      questions:
      - How do I create a new, empty knowledge base before adding documents?
      - Can I restrict a new knowledge base so only I can access it?
      - Is it possible to connect a new knowledge base to an external knowledge API?
      instructions:
      - text: Create a knowledge base called {name}.
        slots:
          name: requestBody.name
      - text: Create knowledge base {name} with {indexing_technique} indexing and permission {permission}.
        slots:
          name: requestBody.name
          indexing_technique: requestBody.indexing_technique
          permission: requestBody.permission
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a knowledge base's settings and stats
      effect: read
      questions:
      - What embedding model and retrieval settings does a knowledge base use?
      - How many documents are in a specific knowledge base?
      instructions:
      - text: Show the details of knowledge base {dataset_id}.
        slots:
          dataset_id: path.dataset_id
      - text: Get the embedding model and document statistics for {dataset_id}.
        slots:
          dataset_id: path.dataset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a knowledge base
      effect: destructive
      questions:
      - What happens to the documents when I delete an entire knowledge base?
      - Can I remove a knowledge base I no longer use?
      instructions:
      - text: Delete knowledge base {dataset_id}.
        slots:
          dataset_id: path.dataset_id
      - text: Permanently remove knowledge base {dataset_id} and all of its documents.
        slots:
          dataset_id: path.dataset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a knowledge base's name or settings
      effect: write
      questions:
      - Can I rename an existing knowledge base or change its description?
      - How do I share an existing knowledge base with only some team members?
      - Is it possible to switch the embedding model on a knowledge base I already have?
      instructions:
      - text: Rename knowledge base {dataset_id} to {name}.
        slots:
          dataset_id: path.dataset_id
          name: requestBody.name
      - text: Change the access permission of knowledge base {dataset_id} to {permission}.
        slots:
          dataset_id: path.dataset_id
          permission: requestBody.permission
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/retrieve'].post
  update:
    x-apievangelist-phrasing:
      intent: Search a knowledge base for relevant chunks
      effect: read
      questions:
      - How do I test which chunks my knowledge base returns for a question?
      - Can I run retrieval against a knowledge base from my own code?
      instructions:
      - text: Search knowledge base {dataset_id} for {query}.
        slots:
          dataset_id: path.dataset_id
          query: requestBody.query
      - text: Run a test retrieval of {query} against {dataset_id} and show the top chunks.
        slots:
          query: requestBody.query
          dataset_id: path.dataset_id
      method: generated
      generated: '2026-09-26'