openapi: 3.2.0
info:
  title: Dify Service Knowledge Bases API
  description: REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key.
  version: 1.0.0
servers:
- url: https://{api_base_url}
  description: Base URL of the Dify Service API. For self-hosted deployments, replace it with your own API base URL.
  variables:
    api_base_url:
      default: api.dify.ai/v1
      description: Host and path of the API base URL, without the `https://` prefix.
security:
- ApiKeyAuth: []
tags:
- name: Knowledge Bases
  description: Operations for managing knowledge bases, including creation, configuration, and retrieval.
paths:
  /datasets:
    post:
      tags:
      - Knowledge Bases
      summary: Create an Empty Knowledge Base
      description: Creates an empty knowledge base. Add documents to it with Create Document by Text or Create Document by File.
      operationId: createDataset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 40
                  description: Name of the knowledge base.
                description:
                  type: string
                  maxLength: 400
                  default: ''
                  description: Description of the knowledge base.
                indexing_technique:
                  type:
                  - string
                  - 'null'
                  enum:
                  - high_quality
                  - economy
                  description: '`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing.'
                permission:
                  type: string
                  enum:
                  - only_me
                  - all_team_members
                  - partial_members
                  default: only_me
                  description: Controls who can access this knowledge base. `only_me` restricts to the creator, `all_team_members` grants access to the entire workspace, `partial_members` grants access to specified members.
                provider:
                  type: string
                  enum:
                  - vendor
                  - external
                  default: vendor
                  description: '`vendor` for internal knowledge base, `external` for external knowledge base.'
                embedding_model:
                  type: string
                  description: Embedding model name. Use the `model` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`.
                embedding_model_provider:
                  type: string
                  description: 'Embedding model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/openai/openai`). A bare name like `openai` expands to `langgenius/<name>/<name>` and works only for langgenius-published plugins.


                    Get valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`.'
                retrieval_model:
                  $ref: '#/components/schemas/RetrievalModel'
                  description: Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base.
                external_knowledge_api_id:
                  type: string
                  description: ID of the external knowledge API connection.
                external_knowledge_id:
                  type: string
                  description: ID of the external knowledge base.
                summary_index_setting:
                  type:
                  - object
                  - 'null'
                  description: Summary index configuration.
                  properties:
                    enable:
                      type: boolean
                      description: Whether to enable summary indexing.
                    model_name:
                      type: string
                      description: Name of the model used for generating summaries.
                    model_provider_name:
                      type: string
                      description: Provider of the summary generation model.
                    summary_prompt:
                      type: string
                      description: Custom prompt template for summary generation.
      responses:
        '200':
          description: Knowledge base created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
              examples:
                success:
                  summary: Response Example
                  value:
                    id: c42e2a6e-40b3-4330-96f8-f1e4d768e8c9
                    name: Product Documentation
                    description: Technical documentation for the product API
                    provider: vendor
                    permission: only_me
                    data_source_type: null
                    indexing_technique: high_quality
                    app_count: 0
                    document_count: 0
                    word_count: 0
                    created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
                    author_name: admin
                    created_at: 1741267200
                    updated_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
                    updated_at: 1741267200
                    embedding_model: text-embedding-3-small
                    embedding_model_provider: langgenius/openai/openai
                    embedding_available: true
                    retrieval_model_dict:
                      search_method: semantic_search
                      reranking_enable: false
                      reranking_mode: null
                      reranking_model:
                        reranking_provider_name: ''
                        reranking_model_name: ''
                      weights: null
                      top_k: 3
                      score_threshold_enabled: false
                      score_threshold: null
                    tags: []
                    doc_form: text_model
                    external_knowledge_info: null
                    external_retrieval_model: null
                    doc_metadata: []
                    built_in_field_enabled: true
                    pipeline_id: null
                    runtime_mode: null
                    chunk_structure: null
                    icon_info: null
                    summary_index_setting: null
                    is_published: false
                    total_documents: 0
                    total_available_documents: 0
                    enable_api: true
                    is_multimodal: false
                    maintainer: admin
        '400':
          description: '`invalid_param` : The embedding or reranking model you specified is not configured or available.'
          content:
            application/json:
              examples:
                invalid_param:
                  summary: invalid_param
                  value:
                    status: 400
                    code: invalid_param
                    message: No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider.
        '403':
          description: '`forbidden` : Your subscription''s knowledge base request rate limit has been reached.'
          content:
            application/json:
              examples:
                forbidden:
                  summary: forbidden (rate limit)
                  value:
                    status: 403
                    code: forbidden
                    message: Sorry, you have reached the knowledge base request rate limit of your subscription.
        '409':
          description: '`dataset_name_duplicate` : A knowledge base with the same name already exists.'
          content:
            application/json:
              examples:
                dataset_name_duplicate:
                  summary: dataset_name_duplicate
                  value:
                    status: 409
                    code: dataset_name_duplicate
                    message: The dataset name already exists. Please modify your dataset name.
      x-mint:
        href: /en/api-reference/knowledge-bases/create-an-empty-knowledge-base
        metadata:
          title: Create an Empty Knowledge Base
          sidebarTitle: Create an Empty Knowledge Base
    get:
      tags:
      - Knowledge Bases
      summary: List Knowledge Bases
      description: Returns a paginated list of knowledge bases, optionally filtered by keyword or tags.
      operationId: listDatasets
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          default: 1
        description: Page number.
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
        description: Number of items per page.
      - name: keyword
        in: query
        schema:
          type: string
        description: Search keyword to filter by name.
      - name: include_all
        in: query
        schema:
          type: boolean
          default: false
        description: Whether to include all knowledge bases regardless of permissions.
      - name: tag_ids
        in: query
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
        description: Tag IDs to filter by. Get tag IDs from [List Knowledge Type Tags](/en/api-reference/tags/list-knowledge-tags).
      responses:
        '200':
          description: List of knowledge bases.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Array of knowledge base objects.
                    items:
                      $ref: '#/components/schemas/Dataset'
                  has_more:
                    type: boolean
                    description: Whether more items exist on the next page.
                  limit:
                    type: integer
                    description: Number of items per page.
                  total:
                    type: integer
                    description: Total number of matching items.
                  page:
                    type: integer
                    description: Current page number.
              examples:
                success:
                  summary: Response Example
                  value:
                    data:
                    - id: c42e2a6e-40b3-4330-96f8-f1e4d768e8c9
                      name: Product Documentation
                      description: Technical documentation for the product API
                      provider: vendor
                      permission: only_me
                      data_source_type: null
                      indexing_technique: high_quality
                      app_count: 0
                      document_count: 0
                      word_count: 0
                      created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
                      author_name: admin
                      created_at: 1741267200
                      updated_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
                      updated_at: 1741267200
                      embedding_model: text-embedding-3-small
                      embedding_model_provider: langgenius/openai/openai
                      embedding_available: true
                      retrieval_model_dict:
                        search_method: semantic_search
                        reranking_enable: false
                        reranking_mode: null
                        reranking_model:
                          reranking_provider_name: ''
                          reranking_model_name: ''
                        weights: null
                        top_k: 3
                        score_threshold_enabled: false
                        score_threshold: null
                      tags: []
                      doc_form: text_model
                      external_knowledge_info: null
                      external_retrieval_model: null
                      doc_metadata: []
                      built_in_field_enabled: true
                      pipeline_id: null
                      runtime_mode: null
                      chunk_structure: null
                      icon_info: null
                      summary_index_setting: null
                      is_published: false
                      total_documents: 0
                      total_available_documents: 0
                      enable_api: true
                      is_multimodal: false
                      maintainer: admin
                    has_more: false
                    limit: 20
                    total: 1
                    page: 1
      x-mint:
        href: /en/api-reference/knowledge-bases/list-knowledge-bases
        metadata:
          title: List Knowledge Bases
          sidebarTitle: List Knowledge Bases
  /datasets/{dataset_id}:
    get:
      tags:
      - Knowledge Bases
      summary: Get Knowledge Base
      description: Returns detailed information about a knowledge base, including its embedding model, retrieval configuration, and document statistics.
      operationId: getDatasetDetail
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
      responses:
        '200':
          description: Knowledge base details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
              examples:
                success:
                  summary: Response Example
                  value:
                    id: c42e2a6e-40b3-4330-96f8-f1e4d768e8c9
                    name: Product Documentation
                    description: Technical documentation for the product API
                    provider: vendor
                    permission: only_me
                    data_source_type: null
                    indexing_technique: high_quality
                    app_count: 0
                    document_count: 0
                    word_count: 0
                    created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
                    author_name: admin
                    created_at: 1741267200
                    updated_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
                    updated_at: 1741267200
                    embedding_model: text-embedding-3-small
                    embedding_model_provider: langgenius/openai/openai
                    embedding_available: true
                    retrieval_model_dict:
                      search_method: semantic_search
                      reranking_enable: false
                      reranking_mode: null
                      reranking_model:
                        reranking_provider_name: ''
                        reranking_model_name: ''
                      weights: null
                      top_k: 3
                      score_threshold_enabled: false
                      score_threshold: null
                    tags: []
                    doc_form: text_model
                    external_knowledge_info: null
                    external_retrieval_model: null
                    doc_metadata: []
                    built_in_field_enabled: true
                    pipeline_id: null
                    runtime_mode: null
                    chunk_structure: null
                    icon_info: null
                    summary_index_setting: null
                    is_published: false
                    total_documents: 0
                    total_available_documents: 0
                    enable_api: true
                    is_multimodal: false
                    maintainer: admin
        '403':
          description: '`forbidden` : API access is not enabled for this knowledge base.'
          content:
            application/json:
              examples:
                forbidden:
                  summary: forbidden (api access)
                  value:
                    status: 403
                    code: forbidden
                    message: Dataset api access is not enabled.
        '404':
          description: '`not_found` : No knowledge base matches `dataset_id`.'
          content:
            application/json:
              examples:
                not_found:
                  summary: not_found
                  value:
                    status: 404
                    code: not_found
                    message: Dataset not found.
      x-mint:
        href: /en/api-reference/knowledge-bases/get-knowledge-base
        metadata:
          title: Get Knowledge Base
          sidebarTitle: Get Knowledge Base
    patch:
      tags:
      - Knowledge Bases
      summary: Update Knowledge Base
      description: Updates a knowledge base. Only the fields included in the request body are changed.
      operationId: updateDataset
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 40
                  description: Name of the knowledge base.
                description:
                  type: string
                  maxLength: 400
                  description: Description of the knowledge base.
                indexing_technique:
                  type:
                  - string
                  - 'null'
                  enum:
                  - high_quality
                  - economy
                  description: '`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing.'
                permission:
                  type: string
                  enum:
                  - only_me
                  - all_team_members
                  - partial_members
                  description: Controls who can access this knowledge base. `only_me` restricts to the creator, `all_team_members` grants access to the entire workspace, `partial_members` grants access to specified members.
                embedding_model:
                  type: string
                  description: Embedding model name. Use the `model` field from [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`.
                embedding_model_provider:
                  type: string
                  description: 'Embedding model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/openai/openai`). A bare name like `openai` expands to `langgenius/<name>/<name>` and works only for langgenius-published plugins.


                    Get valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=text-embedding`.'
                retrieval_model:
                  $ref: '#/components/schemas/RetrievalModel'
                  description: Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base.
                partial_member_list:
                  type: array
                  description: List of team members with access when `permission` is `partial_members`.
                  items:
                    type: object
                    properties:
                      user_id:
                        type: string
                        description: ID of the team member to grant access.
                external_retrieval_model:
                  type: object
                  description: Retrieval settings for external knowledge bases.
                  properties:
                    top_k:
                      type: integer
                      description: Maximum number of results to return.
                    score_threshold:
                      type: number
                      description: Minimum similarity score threshold for filtering results.
                    score_threshold_enabled:
                      type: boolean
                      description: Whether score threshold filtering is enabled.
                external_knowledge_id:
                  type: string
                  description: ID of the external knowledge base.
                external_knowledge_api_id:
                  type: string
                  description: ID of the external knowledge API connection.
      responses:
        '200':
          description: Knowledge base updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
              examples:
                success:
                  summary: Response Example
                  value:
                    id: c42e2a6e-40b3-4330-96f8-f1e4d768e8c9
                    name: Product Documentation
                    description: Technical documentation for the product API
                    provider: vendor
                    permission: only_me
                    data_source_type: null
                    indexing_technique: high_quality
                    app_count: 0
                    document_count: 0
                    word_count: 0
                    created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
                    author_name: admin
                    created_at: 1741267200
                    updated_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
                    updated_at: 1741267200
                    embedding_model: text-embedding-3-small
                    embedding_model_provider: langgenius/openai/openai
                    embedding_available: true
                    retrieval_model_dict:
                      search_method: semantic_search
                      reranking_enable: false
                      reranking_mode: null
                      reranking_model:
                        reranking_provider_name: ''
                        reranking_model_name: ''
                      weights: null
                      top_k: 3
                      score_threshold_enabled: false
                      score_threshold: null
                    tags: []
                    doc_form: text_model
                    external_knowledge_info: null
                    external_retrieval_model: null
                    doc_metadata: []
                    built_in_field_enabled: true
                    pipeline_id: null
                    runtime_mode: null
                    chunk_structure: null
                    icon_info: null
                    summary_index_setting: null
                    is_published: false
                    total_documents: 0
                    total_available_documents: 0
                    enable_api: true
                    is_multimodal: false
                    maintainer: admin
                    partial_member_list: []
        '400':
          description: '`invalid_param` : The embedding or reranking model you specified is not configured or available.'
          content:
            application/json:
              examples:
                invalid_param:
                  summary: invalid_param
                  value:
                    status: 400
                    code: invalid_param
                    message: No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider.
        '403':
          description: '- `forbidden` : API access is not enabled for this knowledge base.

            - `forbidden` : Your subscription''s knowledge base request rate limit has been reached.'
          content:
            application/json:
              examples:
                forbidden_1:
                  summary: forbidden (api access)
                  value:
                    status: 403
                    code: forbidden
                    message: Dataset api access is not enabled.
                forbidden_2:
                  summary: forbidden (rate limit)
                  value:
                    status: 403
                    code: forbidden
                    message: Sorry, you have reached the knowledge base request rate limit of your subscription.
        '404':
          description: '`not_found` : No knowledge base matches `dataset_id`.'
          content:
            application/json:
              examples:
                not_found:
                  summary: not_found
                  value:
                    status: 404
                    code: not_found
                    message: Dataset not found.
      x-mint:
        href: /en/api-reference/knowledge-bases/update-knowledge-base
        metadata:
          title: Update Knowledge Base
          sidebarTitle: Update Knowledge Base
    delete:
      tags:
      - Knowledge Bases
      summary: Delete Knowledge Base
      description: Permanently deletes a knowledge base and all of its documents.
      operationId: deleteDataset
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
      responses:
        '204':
          description: Knowledge base deleted successfully.
        '403':
          description: '- `forbidden` : API access is not enabled for this knowledge base.

            - `forbidden` : Your subscription''s knowledge base request rate limit has been reached.'
          content:
            application/json:
              examples:
                forbidden_1:
                  summary: forbidden (api access)
                  value:
                    status: 403
                    code: forbidden
                    message: Dataset api access is not enabled.
                forbidden_2:
                  summary: forbidden (rate limit)
                  value:
                    status: 403
                    code: forbidden
                    message: Sorry, you have reached the knowledge base request rate limit of your subscription.
        '404':
          description: '`not_found` : No knowledge base matches `dataset_id`.'
          content:
            application/json:
              examples:
                not_found:
                  summary: not_found
                  value:
                    status: 404
                    code: not_found
                    message: Dataset not found.
      x-mint:
        href: /en/api-reference/knowledge-bases/delete-knowledge-base
        metadata:
          title: Delete Knowledge Base
          sidebarTitle: Delete Knowledge Base
  /datasets/{dataset_id}/retrieve:
    post:
      tags:
      - Knowledge Bases
      summary: Retrieve Chunks from a Knowledge Base / Test Retrieval
      description: Searches a knowledge base and returns the chunks most relevant to the query, for both production retrieval and test retrieval.
      operationId: retrieveSegments
      parameters:
      - name: dataset_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Knowledge base ID, from [List Knowledge Bases](/en/api-reference/knowledge-bases/list-knowledge-bases).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                  maxLength: 250
                  description: Search query text.
                retrieval_model:
                  $ref: '#/components/schemas/RetrievalModel'
                  description: Retrieval model configuration. Controls how chunks are searched and ranked when querying this knowledge base.
                attachment_ids:
                  type:
                  - array
                  - 'null'
                  items:
                    type: string
                  description: List of attachment IDs to include in the retrieval context.
                external_retrieval_model:
                  type: object
                  description: Retrieval settings for external knowledge bases.
                  properties:
                    top_k:
                      type: integer
                      description: Maximum number of results to return.
                    score_threshold:
                      type: number
                      description: Minimum similarity score threshold for filtering results.
                    score_threshold_enabled:
                      type: boolean
                      description: Whether score threshold filtering is enabled.
      responses:
        '200':
          description: Retrieval results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: object
                    description: The original query object.
                    properties:
                      content:
                        type: string
                        description: The query text.
                  records:
                    type: array
                    description: List of matched retrieval records.
                    items:
                      type: object
                      properties:
                        segment:
                          type: object
                          description: Matched chunk from the knowledge base.
                          properties:
                            id:
                              type: string
                              description: Unique identifier of the chunk.
                            position:
                              type: integer
                              description: Position of the chunk within the document.
                            document_id:
                              type: string
                              description: ID of the document this chunk belongs to.
                            content:
                              type: string
                              description: Text content of the chunk.
                            sign_content:
                              type: string
                              description: Signed content hash for integrity verification.
                            answer:
                              type: string
                              description: Answer content, used in Q&A mode documents.
                            word_count:
                              type: integer
                              description: Word count of the chunk content.
                            tokens:
                              type: integer
                              description: Token count of the chunk content.
                            keywords:
                              type: array
                              description: Keywords associated with this chunk for keyword-based retrieval.
                              items:
                                type: string
                            index_node_id:
                              type: string
                              description: ID of the index node in the vector store.
                            index_node_hash:
                              type: string
                              description: Hash of the indexed content, used to detect changes.
                            hit_count:
                              type: integer
                              description: Number of times this chunk has been matched in retrieval queries.
                            enabled:
                              type: boolean
                              description: Whether the chunk is enabled for retrieval.
                            disabled_at:
                              type:
                              - number
                              - 'null'
                              description: Timestamp when the chunk was disabled. `null` if enabled.
                            disabled_by:
                              type:
                              - string
                              - 'null'
                              description: ID of the user who disabled the chunk. `null` if enabled.
                            status:
                              type: string
                              description: Indexing status of the chunk.
                            created_by:
                              type: string
                              description: ID of the user who created the chunk.
                            created_at:
                              type: number
                              description: Creation timestamp (Unix epoch in seconds).
                            indexing_at:
                              type:
                              - number
                              - 'null'
                              description: Timestamp when indexing started. `null` if not yet started.
                            completed_at:
                              type:
                              - number
                              - 'null'
                              description: Timestamp when indexing completed. `null` if not yet completed.
                            error:
                              type:
                              - string
                              - 'null'
                              description: Error message if indexing failed. `null` when no error.
                            stopped_at:
                              type:
                              - number
                              - 'null'
                              description: Timestamp when indexing was stopped. `null` if not stopped.
                            document:
                              type: object
                              description: Parent document information for the matched chunk.
                              properties:
                                id:
                                  type: string
                                  description: Unique identifier of the document.
                                data_source_type:
                                  type: string
                                  description: How the document was created.
                                name:
                                  type: string
                                  description: Document name.
                                doc_type:
                                  type:
                                  - string
                                  - 'null'
                                  description: Document type classification. `null` if not set.
                                doc_metadata:
                                  type:
                                  - object
                                  - 'null'
                                  description: Metadata values for the document. `null` if no metadata is configured.
                        child_chunks:
                          type: array
                          description: Matched child chunks within the chunk, if using hierarchical indexing.
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                description: Unique identifier of the child chunk.
                              content:
                                type: string
                                description: Text content of the child chunk.
                              position:
                                type: integer
                                description: Position of the child chunk within the parent chunk.
                              score:
                                type: number
                                description: Similarity score of the child chunk.
                        score:
                          type: number
                          description: Similarity score.
                        tsne_position:
                          type:
                          - object
                          - 'null'
                          description: t-SNE visualization position.
                        files:
                          type: array
                          description: Files attached to this chunk.
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                description: Attachment file identifier.
                              name:
                                type: string
                                description: Original file name.
                              size:
                                type: integer
                                description: File size in bytes.
                              extension:
                                type: string
                                description: File extension.
                              mime_type:
                                type: string
                                description: MIME type of the file.
                              source_url:
                                type: string
                                description: URL to access the attachment.
                        summary:
                          type:
                          - string
                          - 'null'
                          description: Summary content if retrieved via summary index.
              examples:
                success:
                  summary: Response Example
                  value:
                    query:
                      content: What is Dify?
                    records:
                    - segment:
                        id: f3d1c7be-9f3a-40d8-8eb8-3a1ef9c3f2c1
                        position: 1
                        document_id: a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac
                        content: Dify is an open-source LLM app development platform.
                        sign_content: ''
                        answer: ''
                        word_count: 9
                        tokens: 12
                        keywords:
                        - dify
                        - platform
                        - llm
                        index_node_id: a1b2c3d4-e5f6-7890-abcd-000000000001
                        index_node_hash: abc123def456
                        hit_count: 1
                        enabled: true
                        disabled_at: null
                        disabled_by: null
                        status: completed
                        created_by: ad313dd6-ef04-4dd1-a5b0-c0f0b9e2e7e4
                        created_at: 1741267200
                        indexing_at: 1741267200
                        completed_at: 1741267200
                        error: null
                        stopped_at: null
                        document:
                          id: a8e0e5b5-78c6-4130-a5ce-25feb0e0b4ac
                          data_source_type: upload_file
                          name: guide.txt
                          doc_type: null
                          doc_metadata: null
                      child_chunks: []
                      score: 0.92
                      tsne_position: null
                      files: []
                      summary: null
        '400':
          description: '- `dataset_not_initialized` : The knowledge base is still initializing or indexing.

            - `provider_not_initialize` : The model provider has no valid credentials configured.

            - `provider_quota_exceeded` : The Dify-hosted model provider quota is exhausted.

            - `model_currently_not_support` : The selected model is not currently supported.

            - `completion_request_error` : The model request failed.

            - `invalid_param` : A request parameter is invalid.'
          content:
            application/json:
              examples:
                dataset_not_initialized:
                  summary: dataset_not_initialized
                  value:
                    status: 400
                    code: dataset_not_initialized
                    message: The dataset is still being initialized or indexing. Please wait a moment.
                provider_not_initialize:
                  summary: provider_not_initialize
                  value:
                    status: 400
                    code: provider_not_initialize
                    message: No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.
                provider_quota_exceeded:
                  summary: provider_quota_exceeded
                  value:
                    status: 400
                    code: provider_quota_exceeded
                    message: Your quota for Dify Hosted Model Provider has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.
                model_currently_not_support:
                  summary: model_currently_not_support
                  value:
                    status: 400
                    code: model_currently_not_support
                    message: Dify Hosted OpenAI trial currently not support the GPT-4 model.
                completion_request_error:
                  summary: completion_request_error
                  value:
                    status: 400
                    code: completion_request_error
                    message: Completion request failed.
                invalid_param:
                  summary: invalid_param
                  value:
                    status: 400
                    code: invalid_param
                    message: Invalid parameter value.
        '403':
          description: '- `forbidden` : API access is not enabled for this knowledge base.

            - `forbidden` : Your subscription''s knowledge base request rate limit has been reached.'
          content:
            application/json:
              examples:
                forbidden_1:
                  summary: forbidden (api access)
                  value:
                    status: 403
                    code: forbidden
                    message: Dataset api access is not enabled.
                forbidden_2:
                  summary: forbidden (rate limit)
                  value:
                    status: 403
                    code: forbidden
                    message: Sorry, you have reached the knowledge base request rate limit of your subscription.
        '404':
          description: '`not_found` : No knowledge base matches `dataset_id`.'
          content:
            application/json:
              examples:
                not_found:
                  summary: not_found
                  value:
                    status: 404
                    code: not_found
                    message: Dataset not found.
        '500':
          description: '`internal_server_error` : An internal error occurred during retrieval.'
          content:
            application/json:
              examples:
                internal_server_error:
                  summary: internal_server_error
                  value:
                    status: 500
                    code: internal_server_error
                    message: An internal error occurred.
      x-mint:
        href: /en/api-reference/knowledge-bases/retrieve-chunks-from-a-knowledge-base-test-retrieval
        metadata:
          title: Retrieve Chunks from a Knowledge Base / Test Retrieval
          sidebarTitle: Retrieve Chunks from a Knowledge Base / Test Retrieval
components:
  schemas:
    RetrievalModel:
      type: object
      required:
      - search_method
      - reranking_enable
      - top_k
      - score_threshold_enabled
      properties:
        search_method:
          type: string
          description: Search method used for retrieval.
          enum:
          - keyword_search
          - semantic_search
          - full_text_search
          - hybrid_search
        reranking_enable:
          type: boolean
          description: Whether reranking is enabled.
        reranking_model:
          type: object
          description: Reranking model configuration.
          properties:
            reranking_provider_name:
              type: string
              description: 'Reranking model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/cohere/cohere`). A bare name like `cohere` expands to `langgenius/<name>/<name>` and works only for langgenius-published plugins.


                Get valid values from the `provider` field of [Get Available Models](/en/api-reference/models/get-available-models) with `model_type=rerank`.'
            reranking_model_name:
              type: string
              description: Name of the reranking model.
        reranking_mode:
          type:
          - string
          - 'null'
          enum:
          - reranking_model
          - weighted_score
          description: Reranking mode. Required when `reranking_enable` is `true`.
        top_k:
          type: integer
          description: Maximum number of results to return.
        score_threshold_enabled:
          type: boolean
          description: Whether score threshold filtering is enabled.
        score_threshold:
          type:
          - number
          - 'null'
          description: Minimum similarity score for results. Only effective when `score_threshold_enabled` is `true`.
        weights:
          type:
          - object
          - 'null'
          description: Weight configuration for hybrid search.
          properties:
            weight_type:
              type: string
              description: Strategy for balancing semantic and keyword search weights.
              enum:
              - semantic_first
              - keyword_first
              - customized
            vector_setting:
              type: object
              description: Semantic search weight settings.
              properties:
                vector_weight:
                  type: number
                  description: Weight assigned to semantic (vector) search results.
                embedding_provider_name:
                  type: string
                  description: Provider of the embedding model used for vector search.
                embedding_model_name:
                  type: string
                  description: Name of the embedding model used for vector search.
            keyword_setting:
              type: object
              description: Keyword search weight settings.
              properties:
                keyword_weight:
                  type: number
                  description: Weight assigned to keyword search results.
        metadata_filtering_conditions:
          type:
          - object
          - 'null'
          description: Restrict retrieval to chunks whose document metadata matches the given conditions. Conditions are evaluated server-side against document metadata fields.
          properties:
            logical_operator:
              type:
              - string
              - 'null'
              enum:
              - and
              - or
              default: and
              description: How to combine multiple conditions.
            conditions:
              type:
              - array
              - 'null'
              description: List of metadata conditions to evaluate.
              items:
                type: object
                required:
                - name
                - comparison_operator
                properties:
                  name:
                    type: string
                    description: Metadata field name to compare against.
                  comparison_operator:
                    type: string
                    description: 'Comparison to apply, by metadata type:


                      - String or array metadata: `contains`, `not contains`, `start with`, `end with`, `is`, `is not`, `empty`, `not empty`, `in`, `not in`

                      - Numeric metadata: `=`, `≠`, `>`, `<`, `≥`, `≤`

                      - Time metadata: `before`, `after`'
                    enum:
                    - contains
                    - not contains
                    - start with
                    - end with
                    - is
                    - is not
                    - empty
                    - not empty
                    - in
                    - not in
                    - '='
                    - ≠
                    - '>'
                    - <
                    - ≥
                    - ≤
                    - before
                    - after
                  value:
                    description: 'Value to compare against. Type depends on `comparison_operator`: string for most string operators, array of strings for `in` and `not in`, number for numeric operators, and omitted for `empty` and `not empty`.'
                    oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
                    - type: number
    Dataset:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the knowledge base.
        name:
          type: string
          description: Display name of the knowledge base. Unique within the workspace.
        description:
          type: string
          description: Optional text describing the purpose or contents of the knowledge base.
        provider:
          type: string
          description: Provider type. `vendor` for internally managed, `external` for external knowledge base connections.
        permission:
          type: string
          description: 'Controls who can access this knowledge base. Possible values: `only_me`, `all_team_members`, `partial_members`.'
        data_source_type:
          type: string
          description: Data source type of the documents, `null` if not yet configured.
        indexing_technique:
          type: string
          description: '`high_quality` uses embedding models for precise search; `economy` uses keyword-based indexing.'
        app_count:
          type: integer
          description: Number of applications currently using this knowledge base.
        document_count:
          type: integer
          description: Total number of documents in the knowledge base.
        word_count:
          type: integer
          description: Total word count across all documents.
        created_by:
          type: string
          description: ID of the user who created the knowledge base.
        author_name:
          type: string
          description: Display name of the creator.
        created_at:
          type: number
          description: Creation timestamp (Unix epoch in seconds).
        updated_by:
          type: string
          description: ID of the user who last updated the knowledge base.
        updated_at:
          type: number
          description: Last update timestamp (Unix epoch in seconds).
        embedding_model:
          type: string
          description: Name of the embedding model used for indexing.
        embedding_model_provider:
          type: string
          description: Embedding model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/openai/openai`). Legacy knowledge bases may return the bare short form (e.g. `openai`).
        embedding_available:
          type: boolean
          description: Whether the configured embedding model is currently available.
        retrieval_model_dict:
          type: object
          description: Retrieval configuration for the knowledge base.
          properties:
            search_method:
              type: string
              description: Search method used for retrieval. `keyword_search` for keyword matching, `semantic_search` for embedding-based similarity, `full_text_search` for full-text indexing, `hybrid_search` for a combination of semantic and keyword approaches.
            reranking_enable:
              type: boolean
              description: Whether reranking is enabled.
            reranking_mode:
              type:
              - string
              - 'null'
              description: Reranking mode. `reranking_model` for model-based reranking, `weighted_score` for score-based weighting. `null` if reranking is disabled.
            reranking_model:
              type: object
              description: Reranking model configuration.
              properties:
                reranking_provider_name:
                  type: string
                  description: Reranking model provider identifier, formatted as `organization/plugin_name/provider_name` (e.g. `langgenius/cohere/cohere`). Legacy knowledge bases may return the bare short form (e.g. `cohere`).
                reranking_model_name:
                  type: string
                  description: Name of the reranking model.
            weights:
              type:
              - object
              - 'null'
              description: Weight configuration for hybrid search.
              properties:
                weight_type:
                  type: string
                  description: Strategy for balancing semantic and keyword search weights.
                vector_setting:
                  type: object
                  description: Semantic search weight settings.
                  properties:
                    vector_weight:
                      type: number
                      description: Weight assigned to semantic (vector) search results.
                    embedding_provider_name:
                      type: string
                      description: Provider of the embedding model used for vector search.
                    embedding_model_name:
                      type: string
                      description: Name of the embedding model used for vector search.
                keyword_setting:
                  type: object
                  description: Keyword search weight settings.
                  properties:
                    keyword_weight:
                      type: number
                      description: Weight assigned to keyword search results.
            top_k:
              type: integer
              description: Maximum number of results to return.
            score_threshold_enabled:
              type: boolean
              description: Whether score threshold filtering is enabled.
            score_threshold:
              type: number
              description: Minimum similarity score for results. Only effective when `score_threshold_enabled` is `true`.
        summary_index_setting:
          type:
          - object
          - 'null'
          description: Summary index configuration.
          properties:
            enable:
              type: boolean
              description: Whether summary indexing is enabled.
            model_name:
              type: string
              description: Name of the model used for generating summaries.
            model_provider_name:
              type: string
              description: Provider of the summary generation model.
            summary_prompt:
              type: string
              description: Prompt template used for summary generation.
        tags:
          type: array
          description: Tags associated with this knowledge base.
          items:
            type: object
            properties:
              id:
                type: string
                description: Tag identifier.
              name:
                type: string
                description: Tag name.
              type:
                type: string
                description: Tag type. Always `knowledge` for knowledge base tags.
        doc_form:
          type: string
          description: Document chunking mode. `text_model` for standard text chunking, `hierarchical_model` for parent-child structure, `qa_model` for QA pair extraction.
        external_knowledge_info:
          type:
          - object
          - 'null'
          description: Connection details for external knowledge bases. Present when `provider` is `external`.
          properties:
            external_knowledge_id:
              type: string
              description: ID of the external knowledge base.
            external_knowledge_api_id:
              type: string
              description: ID of the external knowledge API connection.
            external_knowledge_api_name:
              type: string
              description: Display name of the external knowledge API.
            external_knowledge_api_endpoint:
              type: string
              description: Endpoint URL of the external knowledge API.
        external_retrieval_model:
          type:
          - object
          - 'null'
          description: Retrieval settings for external knowledge bases. `null` for internal knowledge bases.
          properties:
            top_k:
              type: integer
              description: Maximum number of results to return from the external knowledge base.
            score_threshold:
              type: number
              description: Minimum similarity score threshold.
            score_threshold_enabled:
              type: boolean
              description: Whether score threshold filtering is enabled.
        doc_metadata:
          type: array
          description: Metadata field definitions for the knowledge base.
          items:
            type: object
            properties:
              id:
                type: string
                description: Metadata field identifier.
              name:
                type: string
                description: Metadata field name.
              type:
                type: string
                description: Metadata field value type.
        built_in_field_enabled:
          type: boolean
          description: Whether built-in metadata fields (e.g., `document_name`, `uploader`) are enabled.
        pipeline_id:
          type:
          - string
          - 'null'
          description: Pipeline ID, if a custom processing pipeline is configured.
        runtime_mode:
          type:
          - string
          - 'null'
          description: Runtime processing mode.
        chunk_structure:
          type:
          - string
          - 'null'
          description: Chunk structure configuration.
        icon_info:
          type:
          - object
          - 'null'
          description: Icon display configuration for the knowledge base.
          properties:
            icon_type:
              type: string
              description: Type of icon.
            icon:
              type: string
              description: Icon identifier or emoji.
            icon_background:
              type: string
              description: Background color for the icon.
            icon_url:
              type: string
              description: URL of a custom icon image.
        is_published:
          type: boolean
          description: Whether the knowledge base is published.
        total_documents:
          type: integer
          description: Total number of documents.
        total_available_documents:
          type: integer
          description: Number of documents that are enabled and available.
        enable_api:
          type: boolean
          description: Whether API access is enabled for this knowledge base.
        is_multimodal:
          type: boolean
          description: Whether multimodal content processing is enabled.
        maintainer:
          type:
          - string
          - 'null'
          description: Display name of the knowledge base maintainer. `null` if not set.
        partial_member_list:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Account IDs of members granted access when `permission` is `partial_members`. Always present on the update response; on the detail response, present only when `permission` is `partial_members`.
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API_KEY
      description: 'Every request authenticates with an API key: `Authorization: Bearer {API_KEY}`. App endpoints take an app API key; knowledge endpoints take a knowledge base API key ([Get Started](/en/api-reference/guides/get-started)).


        Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`).'