# 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 Documents API
  version: 1.0.0
extends: openapi/dify-documents-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: 12
- target: $.paths['/datasets/{dataset_id}/document/create-by-text'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a document to a knowledge base from raw text
      effect: write
      questions:
      - How do I add pasted text as a new document in my Dify knowledge base?
      - Can I choose parent-child or Q&A chunking when creating a document from text?
      - Which indexing technique must I set when adding the very first text document?
      instructions:
      - text: Create a document named {name} in knowledge base {dataset_id} from the text {text}.
        slots:
          name: requestBody.name
          dataset_id: path.dataset_id
          text: requestBody.text
      - text: Add text {text} as document {name} to {dataset_id} using {indexing_technique} indexing.
        slots:
          text: requestBody.text
          name: requestBody.name
          dataset_id: path.dataset_id
          indexing_technique: requestBody.indexing_technique
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/document/create-by-file'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a document to a knowledge base from a file
      effect: write
      questions:
      - Can I upload a PDF or DOCX straight into a knowledge base as a new document?
      - What is the maximum file size for creating a knowledge base document from an upload?
      instructions:
      - text: Upload {file} as a new document in knowledge base {dataset_id}.
        slots:
          file: requestBody.file
          dataset_id: path.dataset_id
      - text: Create a knowledge base document in {dataset_id} from file {file} with settings {data}.
        slots:
          dataset_id: path.dataset_id
          file: requestBody.file
          data: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents'].get
  update:
    x-apievangelist-phrasing:
      intent: List the documents in a knowledge base
      effect: read
      questions:
      - Which documents are in my knowledge base?
      - Can I filter a knowledge base's documents by name or display status?
      instructions:
      - text: List the documents in knowledge base {dataset_id}.
        slots:
          dataset_id: path.dataset_id
      - text: Find documents in {dataset_id} whose name matches {keyword}.
        slots:
          dataset_id: path.dataset_id
          keyword: query.keyword
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/{document_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of a single knowledge base document
      effect: read
      questions:
      - What are the details and metadata of one document in my knowledge base?
      - Can I fetch only a document's metadata without the other fields?
      instructions:
      - text: Show document {document_id} in knowledge base {dataset_id}.
        slots:
          document_id: path.document_id
          dataset_id: path.dataset_id
      - text: Get document {document_id} of {dataset_id} with metadata mode {metadata}.
        slots:
          document_id: path.document_id
          dataset_id: path.dataset_id
          metadata: query.metadata
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/{document_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a document and all its chunks
      effect: destructive
      questions:
      - How do I permanently remove a document from a knowledge base?
      - Are a document's chunks deleted too when I delete the document?
      instructions:
      - text: Delete document {document_id} from knowledge base {dataset_id}.
        slots:
          document_id: path.document_id
          dataset_id: path.dataset_id
      - text: Permanently remove document {document_id} and its chunks from {dataset_id}.
        slots:
          document_id: path.document_id
          dataset_id: path.dataset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/{document_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Replace a document's file and re-index it
      effect: write
      questions:
      - What is the recommended way to replace a document with a newer version of its file?
      - Can I swap the uploaded file behind an existing document and have it re-indexed?
      instructions:
      - text: Replace document {document_id} in {dataset_id} with the new file {file}.
        slots:
          document_id: path.document_id
          dataset_id: path.dataset_id
          file: requestBody.file
      - text: Use the current file-update endpoint to upload {file} over document {document_id} in knowledge base {dataset_id}.
        slots:
          file: requestBody.file
          document_id: path.document_id
          dataset_id: path.dataset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/{document_id}/download'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a download link for a document's original file
      effect: read
      questions:
      - How do I download the original file I uploaded for a single document?
      - Can I get a signed URL to one knowledge base document's source file?
      instructions:
      - text: Get a download link for the original file of document {document_id} in {dataset_id}.
        slots:
          document_id: path.document_id
          dataset_id: path.dataset_id
      - text: Give me a signed URL for document {document_id} from knowledge base {dataset_id}.
        slots:
          document_id: path.document_id
          dataset_id: path.dataset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/{batch}/indexing-status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check indexing progress for a batch of documents
      effect: read
      questions:
      - Has my newly uploaded document finished indexing yet?
      - Which stage is each document in a batch at, and how many chunks are done?
      instructions:
      - text: Check indexing status for batch {batch} in knowledge base {dataset_id}.
        slots:
          batch: path.batch
          dataset_id: path.dataset_id
      - text: Tell me when every document in batch {batch} of {dataset_id} is completed or errored.
        slots:
          batch: path.batch
          dataset_id: path.dataset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/{document_id}/update-by-text'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a document's text, name or chunking rules
      effect: write
      questions:
      - Can I edit the text content of a document that was created from text?
      - Is it possible to rename a document or change its chunking rules without uploading a file?
      instructions:
      - text: Replace the text of document {document_id} in {dataset_id} with {text} and name it {name}.
        slots:
          document_id: path.document_id
          dataset_id: path.dataset_id
          text: requestBody.text
          name: requestBody.name
      - text: Change the chunking process rules of document {document_id} in knowledge base {dataset_id} to {process_rule}.
        slots:
          document_id: path.document_id
          dataset_id: path.dataset_id
          process_rule: requestBody.process_rule
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/{document_id}/update-by-file'].post
  update:
    x-apievangelist-phrasing:
      intent: Replace a document's file (deprecated endpoint)
      effect: write
      questions:
      - Is the older update-by-file endpoint for documents still supported?
      - My integration uses the deprecated update-by-file call; how does it re-index a document?
      instructions:
      - text: Use the deprecated update-by-file endpoint to upload {file} over document {document_id} in {dataset_id}.
        slots:
          file: requestBody.file
          document_id: path.document_id
          dataset_id: path.dataset_id
      - text: Call the legacy update-by-file route for document {document_id} in knowledge base {dataset_id}.
        slots:
          document_id: path.document_id
          dataset_id: path.dataset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/download-zip'].post
  update:
    x-apievangelist-phrasing:
      intent: Download several documents as one ZIP
      effect: read
      questions:
      - Can I download multiple uploaded documents at once as a ZIP archive?
      - Why are documents I created from pasted text missing from my ZIP download?
      instructions:
      - text: Bundle documents {document_ids} from knowledge base {dataset_id} into a ZIP.
        slots:
          document_ids: requestBody.document_ids
          dataset_id: path.dataset_id
      - text: Download a ZIP archive of the files for documents {document_ids} in {dataset_id}.
        slots:
          document_ids: requestBody.document_ids
          dataset_id: path.dataset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/status/{action}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Enable, disable or archive documents in bulk
      effect: write
      questions:
      - How do I disable several documents so they stop being used in retrieval?
      - Can I archive or unarchive a group of documents in one request?
      instructions:
      - text: Apply {action} to documents {document_ids} in knowledge base {dataset_id}.
        slots:
          action: path.action
          document_ids: requestBody.document_ids
          dataset_id: path.dataset_id
      - text: Archive documents {document_ids} in {dataset_id} using action {action}.
        slots:
          document_ids: requestBody.document_ids
          dataset_id: path.dataset_id
          action: path.action
      method: generated
      generated: '2026-09-26'