Dify · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Dify Service Chunks API

10 actions 10 updates phrasing extends openapi/dify-chunks-api-openapi.yml

Generated by API Evangelist Written by API Evangelist tooling for Dify's API. It is a proposal applied on top of the contract, not a document Dify publishes.

View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 10

$.info

$.paths['/datasets/{dataset_id}/documents/{document_id}/segments'].get

$.paths['/datasets/{dataset_id}/documents/{document_id}/segments'].post

$.paths['/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}'].get

$.paths['/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}'].post

$.paths['/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}'].delete

$.paths['/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks'].get

$.paths['/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks'].post

$.paths['/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}'].delete

$.paths['/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}'].patch

OpenAPI Overlay

# 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 Chunks API
  version: 1.0.0
extends: openapi/dify-chunks-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: 9
- target: $.paths['/datasets/{dataset_id}/documents/{document_id}/segments'].get
  update:
    x-apievangelist-phrasing:
      intent: List the chunks in a document
      effect: read
      questions:
      - How do I see how a knowledge base document was split into chunks?
      - Can I list only the chunks that failed indexing or are still indexing?
      - Which chunks of a document contain a particular keyword?
      instructions:
      - text: List the chunks of document {document_id} in knowledge base {dataset_id}.
        slots:
          document_id: path.document_id
          dataset_id: path.dataset_id
      - text: Show chunks in document {document_id} of {dataset_id} with indexing status {status}.
        slots:
          document_id: path.document_id
          dataset_id: path.dataset_id
          status: query.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/{document_id}/segments'].post
  update:
    x-apievangelist-phrasing:
      intent: Add new chunks to a document
      effect: write
      questions:
      - Can I manually add my own chunks of text to an existing document?
      - Is it possible to insert several chunks into a document in one request?
      instructions:
      - text: Add these chunks {segments} to document {document_id} in knowledge base {dataset_id}.
        slots:
          segments: requestBody.segments
          document_id: path.document_id
          dataset_id: path.dataset_id
      - text: Insert new chunks into document {document_id} of 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/{document_id}/segments/{segment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the full details of one chunk
      effect: read
      questions:
      - What is the full content and metadata of a single chunk?
      - Can I look up one specific chunk by its ID?
      instructions:
      - text: Show chunk {segment_id} from document {document_id} in knowledge base {dataset_id}.
        slots:
          segment_id: path.segment_id
          document_id: path.document_id
          dataset_id: path.dataset_id
      - text: Get the details of chunk {segment_id} in document {document_id} of {dataset_id}.
        slots:
          segment_id: path.segment_id
          document_id: path.document_id
          dataset_id: path.dataset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Edit a chunk and re-index it
      effect: write
      questions:
      - Can I fix the text of a parent chunk that was split badly?
      - Does editing a chunk trigger re-indexing of that chunk?
      instructions:
      - text: Update chunk {segment_id} in document {document_id} of {dataset_id} with {segment}.
        slots:
          segment_id: path.segment_id
          document_id: path.document_id
          dataset_id: path.dataset_id
          segment: requestBody.segment
      - text: Change the content of chunk {segment_id} in document {document_id}, knowledge base {dataset_id}, and re-index it.
        slots:
          segment_id: path.segment_id
          document_id: path.document_id
          dataset_id: path.dataset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a chunk
      effect: destructive
      questions:
      - How do I remove an irrelevant chunk from a document so it is never retrieved?
      - Is deleting a chunk permanent?
      instructions:
      - text: Delete chunk {segment_id} from document {document_id} in knowledge base {dataset_id}.
        slots:
          segment_id: path.segment_id
          document_id: path.document_id
          dataset_id: path.dataset_id
      - text: Permanently remove chunk {segment_id} of document {document_id} in {dataset_id}.
        slots:
          segment_id: path.segment_id
          document_id: path.document_id
          dataset_id: path.dataset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks'].get
  update:
    x-apievangelist-phrasing:
      intent: List child chunks under a parent chunk
      effect: read
      questions:
      - Which child chunks sit under a given parent chunk in a parent-child document?
      - Can I search the child chunks of a parent chunk by keyword?
      instructions:
      - text: List child chunks of parent chunk {segment_id} in document {document_id}, knowledge base {dataset_id}.
        slots:
          segment_id: path.segment_id
          document_id: path.document_id
          dataset_id: path.dataset_id
      - text: Find child chunks containing {keyword} under parent {segment_id} of document {document_id} in {dataset_id}.
        slots:
          keyword: query.keyword
          segment_id: path.segment_id
          document_id: path.document_id
          dataset_id: path.dataset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a child chunk to a parent chunk
      effect: write
      questions:
      - How do I add a child chunk under a parent chunk in hierarchical chunking mode?
      - Can I attach extra fine-grained text to an existing parent chunk?
      instructions:
      - text: Add a child chunk with text {content} under parent {segment_id} of document {document_id} in {dataset_id}.
        slots:
          content: requestBody.content
          segment_id: path.segment_id
          document_id: path.document_id
          dataset_id: path.dataset_id
      - text: Create a new child chunk beneath parent chunk {segment_id} in document {document_id}, knowledge base {dataset_id}, reading {content}.
        slots:
          segment_id: path.segment_id
          document_id: path.document_id
          dataset_id: path.dataset_id
          content: requestBody.content
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a child chunk
      effect: destructive
      questions:
      - Can I remove a single child chunk without deleting its parent?
      - What is the way to drop one child chunk from a parent-child document?
      instructions:
      - text: Delete child chunk {child_chunk_id} under parent {segment_id} of document {document_id} in {dataset_id}.
        slots:
          child_chunk_id: path.child_chunk_id
          segment_id: path.segment_id
          document_id: path.document_id
          dataset_id: path.dataset_id
      - text: Remove child chunk {child_chunk_id} from parent chunk {segment_id}, document {document_id}, knowledge base {dataset_id}.
        slots:
          child_chunk_id: path.child_chunk_id
          segment_id: path.segment_id
          document_id: path.document_id
          dataset_id: path.dataset_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit the text of a child chunk
      effect: write
      questions:
      - How do I correct the wording of an existing child chunk?
      - Can I rewrite a child chunk's content without touching its parent chunk?
      instructions:
      - text: Change child chunk {child_chunk_id} under parent {segment_id} of document {document_id} in {dataset_id} to {content}.
        slots:
          child_chunk_id: path.child_chunk_id
          segment_id: path.segment_id
          document_id: path.document_id
          dataset_id: path.dataset_id
          content: requestBody.content
      - text: Rewrite the text of child chunk {child_chunk_id} in parent {segment_id}, document {document_id}, knowledge base {dataset_id}.
        slots:
          child_chunk_id: path.child_chunk_id
          segment_id: path.segment_id
          document_id: path.document_id
          dataset_id: path.dataset_id
      method: generated
      generated: '2026-09-26'