{ "openapi": "3.0.1", "info": { "title": "Knowledge API", "description": "API for managing knowledge bases (datasets), documents, and segments, including creation, retrieval, and configuration.", "version": "1.0.0" }, "servers": [ { "url": "{apiBaseUrl}", "description": "The base URL for the Knowledge API.", "variables": { "apiBaseUrl": { "default": "https://api.dify.ai/v1", "description": "Actual base URL of the API" } } } ], "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Datasets", "description": "Operations related to managing knowledge bases (datasets)." }, { "name": "Documents", "description": "Operations for creating, updating, and managing documents within a dataset." }, { "name": "Chunks", "description": "Operations for managing document chunks (segments)." }, { "name": "Metadata & Tags", "description": "Operations for managing dataset tags and metadata." }, { "name": "Models", "description": "Operations for retrieving available models." } ], "paths": { "/datasets": { "post": { "tags": [ "Datasets" ], "summary": "Create an Empty Knowledge Base", "description": "Creates a new, empty knowledge base (dataset) with specified configurations.", "operationId": "createDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatasetRequest" } } } }, "responses": { "200": { "description": "Successfully created dataset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" } } } }, "409": { "$ref": "#/components/responses/DatasetNameDuplicate" } } }, "get": { "tags": [ "Datasets" ], "summary": "Get Knowledge Base List", "description": "Retrieves a list of knowledge bases, with options for pagination and filtering.", "operationId": "listDatasets", "parameters": [ { "name": "keyword", "in": "query", "description": "Search keyword to filter datasets by name.", "schema": { "type": "string" } }, { "name": "tag_ids", "in": "query", "description": "List of tag IDs to filter by. Datasets must have all specified tags.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "page", "in": "query", "description": "Page number for pagination.", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "Number of items to return per page.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "include_all", "in": "query", "description": "Whether to include all datasets. This is effective only for workspace owners.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A paginated list of datasets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetListResponse" } } } } } } }, "/datasets/{dataset_id}": { "get": { "tags": [ "Datasets" ], "summary": "Get Knowledge Base Details", "description": "Fetches the detailed information of a specific knowledge base by its ID.", "operationId": "getDatasetDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The unique identifier of the knowledge base.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detailed information about the dataset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetDetail" } } } } } }, "patch": { "tags": [ "Datasets" ], "summary": "Update Knowledge Base", "description": "Updates the settings of a specific knowledge base.", "operationId": "updateDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The unique identifier of the knowledge base.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDatasetRequest" } } } }, "responses": { "200": { "description": "Successfully updated dataset details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetDetail" } } } }, "409": { "$ref": "#/components/responses/DatasetNameDuplicate" } } }, "delete": { "tags": [ "Datasets" ], "summary": "Delete a Knowledge Base", "description": "Deletes a knowledge base and all its associated documents and data.", "operationId": "deleteDataset", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The unique identifier of the knowledge base to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Successfully deleted the dataset." } } } }, "/datasets/{dataset_id}/document/create-by-text": { "post": { "tags": [ "Documents" ], "summary": "Create a Document from Text", "description": "Creates a new document within an existing knowledge base directly from text content.", "operationId": "createDocumentFromText", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base to add the document to.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentByTextRequest" } } } }, "responses": { "200": { "description": "Document created successfully and is being indexed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreationResponse" } } } } } } }, "/datasets/{dataset_id}/document/create-by-file": { "post": { "tags": [ "Documents" ], "summary": "Create a Document from a File", "description": "Creates a new document within an existing knowledge base by uploading a file.", "operationId": "createDocumentFromFile", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base to add the document to.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "A JSON string containing document metadata and processing rules. See `CreateDocumentByFileRequestData` schema for details.", "example": "{\"indexing_technique\":\"high_quality\",\"process_rule\":{\"mode\":\"custom\", \"rules\": { \"segmentation\": {\"separator\":\"###\", \"max_tokens\":500}}}}" }, "file": { "type": "string", "format": "binary", "description": "The file to upload." } } } } } }, "responses": { "200": { "description": "Document created successfully and is being indexed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreationResponse" } } } }, "400": { "$ref": "#/components/responses/FileError" }, "413": { "$ref": "#/components/responses/FileTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedFileType" } } } }, "/datasets/{dataset_id}/documents/{document_id}/update-by-text": { "post": { "tags": [ "Documents" ], "summary": "Update a Document with Text", "description": "Updates an existing document's content or settings using text.", "operationId": "updateDocumentByText", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base containing the document.", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "The ID of the document to update.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDocumentByTextRequest" } } } }, "responses": { "200": { "description": "Document updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreationResponse" } } } } } } }, "/datasets/{dataset_id}/documents/{document_id}/update-by-file": { "post": { "tags": [ "Documents" ], "summary": "Update a Document with a File", "description": "Updates an existing document by uploading a new file, replacing its content.", "operationId": "updateDocumentByFile", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base containing the document.", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "The ID of the document to update.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "A JSON string containing optional document name and processing rules. See `UpdateDocumentByFileRequestData` schema.", "example": "{\"name\":\"new_name.txt\",\"process_rule\":{\"mode\":\"automatic\"}}" }, "file": { "type": "string", "format": "binary", "description": "The new file to upload." } } } } } }, "responses": { "200": { "description": "Document updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentCreationResponse" } } } } } } }, "/datasets/{dataset_id}/documents/{batch}/indexing-status": { "get": { "tags": [ "Documents" ], "summary": "Get Document Embedding Status (Progress)", "description": "Retrieves the indexing status for a batch of documents, showing the progress of embedding and processing.", "operationId": "getDocumentIndexingStatus", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" } }, { "name": "batch", "in": "path", "required": true, "description": "The batch number returned from the document creation endpoint.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Indexing status of the documents in the batch.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/IndexingStatus" } } } } } } } } } }, "/datasets/{dataset_id}/documents/{document_id}": { "get": { "tags": [ "Documents" ], "summary": "Get Document Detail", "description": "Retrieves detailed information about a single document, including its processing rules and status.", "operationId": "getDocumentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" } }, { "name": "metadata", "in": "query", "description": "Metadata filter: `all` returns all metadata, `only` returns only custom metadata, `without` returns no metadata.", "schema": { "type": "string", "enum": [ "all", "only", "without" ], "default": "all" } } ], "responses": { "200": { "description": "Detailed information about the document.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDetail" } } } } } }, "delete": { "tags": [ "Documents" ], "summary": "Delete a Document", "description": "Deletes a specific document from a knowledge base.", "operationId": "deleteDocument", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "The ID of the document to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Successfully deleted the document." } } } }, "/datasets/{dataset_id}/documents": { "get": { "tags": [ "Documents" ], "summary": "Get the Document List of a Knowledge Base", "description": "Retrieves a paginated list of all documents within a specified knowledge base.", "operationId": "listDocuments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" } }, { "name": "keyword", "in": "query", "description": "Keyword to search for in document names.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number for pagination.", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "Number of items to return per page.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "A paginated list of documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentListResponse" } } } } } } }, "/datasets/{dataset_id}/documents/status/{action}": { "patch": { "tags": [ "Documents" ], "summary": "Update Document Status", "description": "Performs a batch action to update the status of one or more documents (e.g., enable, disable, archive).", "operationId": "batchUpdateDocumentStatus", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" } }, { "name": "action", "in": "path", "required": true, "description": "The action to perform on the documents.", "schema": { "type": "string", "enum": [ "enable", "disable", "archive", "un_archive" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document_ids" ], "properties": { "document_ids": { "type": "array", "description": "A list of document IDs to perform the action on.", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments": { "post": { "tags": [ "Chunks" ], "summary": "Add Chunks to a Document", "description": "Adds one or more new chunks (segments) to a specific document. This is useful for manually adding curated content.", "operationId": "createSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSegmentsRequest" } } } }, "responses": { "200": { "description": "List of newly created segments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentListResponse" } } } } } }, "get": { "tags": [ "Chunks" ], "summary": "Get Chunks from a Document", "description": "Retrieves a paginated list of chunks (segments) from a specific document.", "operationId": "listSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" } }, { "name": "keyword", "in": "query", "description": "Keyword to filter segments by content.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter segments by their indexing status.", "schema": { "type": "string", "example": "completed" } }, { "name": "page", "in": "query", "description": "Page number for pagination.", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "Number of items to return per page.", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated list of segments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentPaginatedResponse" } } } } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}": { "get": { "tags": [ "Chunks" ], "summary": "Get a Chunk Details in a Document", "description": "Retrieves the details of a specific chunk (segment) within a document.", "operationId": "getSegmentDetail", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "The ID of the segment.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Detailed information about the segment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentDetailResponse" } } } } } }, "post": { "tags": [ "Chunks" ], "summary": "Update a Chunk in a Document", "description": "Updates the content, keywords, or status of a specific chunk (segment).", "operationId": "updateSegment", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "The ID of the segment to update.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSegmentRequest" } } } }, "responses": { "200": { "description": "Updated segment details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentDetailResponse" } } } } } }, "delete": { "tags": [ "Chunks" ], "summary": "Delete a Chunk in a Document", "description": "Deletes a specific chunk (segment) from a document.", "operationId": "deleteSegment", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "The ID of the segment to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Successfully deleted the segment." } } } }, "/datasets/{dataset_id}/retrieve": { "post": { "tags": [ "Datasets" ], "summary": "Retrieve Chunks from a Knowledge Base / Test Retrieval", "description": "Performs a search query against a knowledge base to retrieve the most relevant chunks (segments). This endpoint can be used for both production retrieval and test retrieval.", "operationId": "retrieveSegments", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base to retrieve from.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveRequest" } } } }, "responses": { "200": { "description": "List of retrieved segments matching the query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveResponse" } } } } } } }, "/workspaces/current/models/model-types/text-embedding": { "get": { "tags": [ "Models" ], "summary": "Get available embedding models", "description": "Fetches a list of all available text embedding models that can be used for creating and querying knowledge bases.", "operationId": "getAvailableEmbeddingModels", "responses": { "200": { "description": "A list of available embedding models grouped by provider.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelProvider" } } } } } } } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks": { "post": { "tags": [ "Chunks" ], "summary": "Create Child Chunk", "description": "Creates a new child chunk under a parent segment in a document using the hierarchical mode.", "operationId": "createChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "The ID of the parent segment.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChildChunkRequest" } } } }, "responses": { "200": { "description": "Successfully created child chunk.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChildChunkResponse" } } } } } }, "get": { "tags": [ "Chunks" ], "summary": "Get Child Chunks", "description": "Retrieves a list of child chunks for a specific parent segment.", "operationId": "getChildChunks", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "The ID of the parent segment.", "schema": { "type": "string", "format": "uuid" } }, { "name": "keyword", "in": "query", "description": "Search keyword to filter child chunks.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number for pagination.", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "description": "Number of items to return per page.", "schema": { "type": "integer", "default": 20, "maximum": 100 } } ], "responses": { "200": { "description": "A paginated list of child chunks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChildChunkListResponse" } } } } } } }, "/datasets/{dataset_id}/documents/{document_id}/segments/{segment_id}/child_chunks/{child_chunk_id}": { "patch": { "tags": [ "Chunks" ], "summary": "Update Child Chunk", "description": "Updates the content of a specific child chunk.", "operationId": "updateChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "The ID of the parent segment.", "schema": { "type": "string", "format": "uuid" } }, { "name": "child_chunk_id", "in": "path", "required": true, "description": "The ID of the child chunk to update.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChildChunkRequest" } } } }, "responses": { "200": { "description": "Successfully updated child chunk.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChildChunkResponse" } } } } } }, "delete": { "tags": [ "Chunks" ], "summary": "Delete Child Chunk", "description": "Deletes a specific child chunk.", "operationId": "deleteChildChunk", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the knowledge base.", "schema": { "type": "string", "format": "uuid" } }, { "name": "document_id", "in": "path", "required": true, "description": "The ID of the document.", "schema": { "type": "string", "format": "uuid" } }, { "name": "segment_id", "in": "path", "required": true, "description": "The ID of the parent segment.", "schema": { "type": "string", "format": "uuid" } }, { "name": "child_chunk_id", "in": "path", "required": true, "description": "The ID of the child chunk to delete.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Successfully deleted the child chunk." } } } }, "/datasets/tags": { "post": { "tags": [ "Metadata & Tags" ], "summary": "Create New Knowledge Base Type Tag", "description": "Creates a new tag that can be used to categorize knowledge bases.", "operationId": "createKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "description": "The name of the new tag.", "maxLength": 50 } } } } } }, "responses": { "200": { "description": "Successfully created tag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } } } }, "get": { "tags": [ "Metadata & Tags" ], "summary": "Get Knowledge Base Type Tags", "description": "Retrieves a list of all available knowledge base tags.", "operationId": "getKnowledgeTags", "responses": { "200": { "description": "A list of tags.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } } } } }, "patch": { "tags": [ "Metadata & Tags" ], "summary": "Modify Knowledge Base Type Tag Name", "description": "Updates the name of an existing tag.", "operationId": "updateKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["tag_id", "name"], "properties": { "tag_id": { "type": "string", "description": "The ID of the tag to modify.", "format": "uuid" }, "name": { "type": "string", "description": "The new name for the tag.", "maxLength": 50 } } } } } }, "responses": { "200": { "description": "Successfully updated tag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tag" } } } } } }, "delete": { "tags": [ "Metadata & Tags" ], "summary": "Delete Knowledge Base Type Tag", "description": "Deletes a tag. The tag must not be bound to any knowledge bases.", "operationId": "deleteKnowledgeTag", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["tag_id"], "properties": { "tag_id": { "type": "string", "description": "The ID of the tag to delete.", "format": "uuid" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/datasets/tags/binding": { "post": { "tags": [ "Metadata & Tags" ], "summary": "Bind Dataset to Knowledge Base Type Tag", "description": "Binds one or more tags to a specific knowledge base.", "operationId": "bindTagsToDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["target_id", "tag_ids"], "properties": { "target_id": { "type": "string", "description": "The ID of the dataset to bind tags to.", "format": "uuid" }, "tag_ids": { "type": "array", "description": "A list of tag IDs to bind.", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/datasets/tags/unbinding": { "post": { "tags": [ "Metadata & Tags" ], "summary": "Unbind Dataset and Knowledge Base Type Tag", "description": "Unbinds a specific tag from a knowledge base.", "operationId": "unbindTagFromDataset", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["target_id", "tag_id"], "properties": { "target_id": { "type": "string", "description": "The ID of the dataset.", "format": "uuid" }, "tag_id": { "type": "string", "description": "The ID of the tag to unbind.", "format": "uuid" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/Success" } } } }, "/datasets/{dataset_id}/tags": { "get": { "tags": [ "Metadata & Tags" ], "summary": "Query Tags Bound to a Dataset", "description": "Retrieves all tags that are currently bound to a specific dataset.", "operationId": "queryDatasetTags", "parameters": [ { "name": "dataset_id", "in": "path", "required": true, "description": "The ID of the dataset.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A list of tags bound to the dataset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "total": { "type": "integer" } } } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API_KEY", "description": "API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with 'Bearer '. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.**" } }, "responses": { "Success": { "description": "Operation successful.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "string", "example": "success" } } } } } }, "FileError": { "description": "Bad request related to file upload. Could be `no_file_uploaded` or `too_many_files`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "FileTooLarge": { "description": "File size exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnsupportedFileType": { "description": "File type not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "DatasetNameDuplicate": { "description": "The dataset name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "A machine-readable error code." }, "message": { "type": "string", "description": "A human-readable error message." }, "status": { "type": "integer", "description": "The HTTP status code." } }, "example": { "code": "no_file_uploaded", "message": "Please upload your file.", "status": 400 } }, "RetrievalModel": { "type": "object", "properties": { "search_method": { "type": "string", "description": "The search method to use for retrieval.", "enum": [ "hybrid_search", "semantic_search", "full_text_search", "keyword_search" ] }, "reranking_enable": { "type": "boolean", "description": "Whether to enable a reranking model to improve search results." }, "reranking_mode": { "type": "object", "description": "Configuration for the reranking model.", "properties": { "reranking_provider_name": { "type": "string", "description": "The provider of the rerank model." }, "reranking_model_name": { "type": "string", "description": "The name of the rerank model." } }, "nullable": true }, "top_k": { "type": "integer", "description": "The number of top matching results to return." }, "score_threshold_enabled": { "type": "boolean", "description": "Whether to apply a score threshold to filter results." }, "score_threshold": { "type": "number", "format": "float", "description": "The minimum score for a result to be included.", "nullable": true }, "weights": { "type": "number", "format": "float", "description": "The weight of semantic search in a hybrid search mode.", "nullable": true } } }, "PreprocessingRule": { "type": "object", "description": "A rule for preprocessing document content.", "properties": { "id": { "type": "string", "description": "The unique identifier for the preprocessing rule.", "enum": [ "remove_extra_spaces", "remove_urls_emails" ] }, "enabled": { "type": "boolean", "description": "Whether this rule is enabled." } } }, "SegmentationRule": { "type": "object", "description": "Rules for segmenting document content into chunks.", "properties": { "separator": { "type": "string", "description": "The custom delimiter used to separate segments." }, "max_tokens": { "type": "integer", "description": "The maximum number of tokens allowed in a single segment." } } }, "SubChunkSegmentationRule": { "type": "object", "description": "Rules for segmenting parent chunks into smaller child chunks (for hierarchical mode).", "properties": { "separator": { "type": "string", "description": "The delimiter for sub-chunking." }, "max_tokens": { "type": "integer", "description": "The maximum token length for a sub-chunk." }, "chunk_overlap": { "type": "integer", "description": "The number of overlapping tokens between adjacent sub-chunks." } } }, "ProcessRule": { "type": "object", "description": "A set of rules for processing a document, including cleaning and segmentation.", "properties": { "mode": { "type": "string", "description": "The processing mode: automatic, custom, or hierarchical.", "enum": [ "automatic", "custom", "hierarchical" ] }, "rules": { "type": "object", "description": "The specific rules to apply, used when mode is 'custom' or 'hierarchical'.", "properties": { "pre_processing_rules": { "type": "array", "items": { "$ref": "#/components/schemas/PreprocessingRule" } }, "segmentation": { "$ref": "#/components/schemas/SegmentationRule" }, "parent_mode": { "type": "string", "description": "Retrieval mode for parent chunks in hierarchical mode.", "enum": [ "full-doc", "paragraph" ] }, "subchunk_segmentation": { "$ref": "#/components/schemas/SubChunkSegmentationRule" } }, "nullable": true } } }, "CreateDocumentByTextRequest": { "type": "object", "required": [ "name", "text" ], "properties": { "name": { "type": "string", "description": "Name of the document." }, "text": { "type": "string", "description": "Full text content of the document." }, "indexing_technique": { "type": "string", "description": "Indexing technique for the document.", "enum": [ "high_quality", "economy" ] }, "doc_form": { "type": "string", "description": "Format of the indexed content.", "enum": [ "text_model", "hierarchical_model", "qa_model" ] }, "doc_language": { "type": "string", "description": "Language of the document, important for Q&A mode.", "example": "English" }, "process_rule": { "$ref": "#/components/schemas/ProcessRule" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel" }, "embedding_model": { "type": "string", "description": "Name of the embedding model to use." }, "embedding_model_provider": { "type": "string", "description": "Provider of the embedding model." } } }, "CreateDocumentByFileRequestData": { "type": "object", "description": "Metadata and rules for creating a document from a file.", "properties": { "original_document_id": { "type": "string", "description": "ID of an existing document to re-upload or modify.", "format": "uuid" }, "indexing_technique": { "type": "string", "enum": [ "high_quality", "economy" ] }, "doc_form": { "type": "string", "enum": [ "text_model", "hierarchical_model", "qa_model" ] }, "doc_language": { "type": "string", "example": "English" }, "process_rule": { "$ref": "#/components/schemas/ProcessRule" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel" }, "embedding_model": { "type": "string" }, "embedding_model_provider": { "type": "string" } } }, "UpdateDocumentByTextRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "New name for the document (optional)." }, "text": { "type": "string", "description": "New text content for the document (optional)." }, "process_rule": { "$ref": "#/components/schemas/ProcessRule" } } }, "UpdateDocumentByFileRequestData": { "type": "object", "properties": { "name": { "type": "string", "description": "New name for the document (optional)." }, "process_rule": { "$ref": "#/components/schemas/ProcessRule" } } }, "Document": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "position": { "type": "integer" }, "data_source_type": { "type": "string" }, "data_source_info": { "type": "object", "nullable": true }, "dataset_process_rule_id": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "created_from": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "integer", "format": "int64" }, "tokens": { "type": "integer" }, "indexing_status": { "type": "string" }, "error": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" }, "disabled_at": { "type": "integer", "format": "int64", "nullable": true }, "disabled_by": { "type": "string", "format": "uuid", "nullable": true }, "archived": { "type": "boolean" }, "display_status": { "type": "string" }, "word_count": { "type": "integer" }, "hit_count": { "type": "integer" }, "doc_form": { "type": "string" } } }, "DocumentCreationResponse": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" }, "batch": { "type": "string", "description": "A batch identifier for tracking indexing progress." } } }, "CreateDatasetRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name of the knowledge base." }, "description": { "type": "string", "description": "Description of the knowledge base (optional)." }, "indexing_technique": { "type": "string", "description": "The indexing technique to use.", "enum": [ "high_quality", "economy" ] }, "permission": { "type": "string", "description": "Access permissions for the knowledge base.", "enum": [ "only_me", "all_team_members", "partial_members" ] }, "provider": { "type": "string", "description": "The provider of the knowledge base.", "enum": [ "vendor", "external" ] }, "external_knowledge_api_id": { "type": "string", "description": "ID of the external knowledge API (if provider is 'external')." }, "external_knowledge_id": { "type": "string", "description": "ID of the external knowledge (if provider is 'external')." }, "embedding_model": { "type": "string", "description": "Name of the embedding model." }, "embedding_model_provider": { "type": "string", "description": "Provider of the embedding model." }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel" } } }, "Dataset": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "provider": { "type": "string" }, "permission": { "type": "string" }, "data_source_type": { "type": "string", "nullable": true }, "indexing_technique": { "type": "string", "nullable": true }, "app_count": { "type": "integer" }, "document_count": { "type": "integer" }, "word_count": { "type": "integer" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "integer", "format": "int64" }, "updated_by": { "type": "string", "format": "uuid" }, "updated_at": { "type": "integer", "format": "int64" }, "embedding_model": { "type": "string", "nullable": true }, "embedding_model_provider": { "type": "string", "nullable": true }, "embedding_available": { "type": "boolean", "nullable": true } } }, "DatasetListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Dataset" } }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" } } }, "DatasetDetail": { "allOf": [ { "$ref": "#/components/schemas/Dataset" }, { "type": "object", "properties": { "retrieval_model_dict": { "$ref": "#/components/schemas/RetrievalModel" }, "tags": { "type": "array", "items": { "type": "object" } }, "doc_form": { "type": "string", "nullable": true } } } ] }, "UpdateDatasetRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "New name for the knowledge base." }, "description": { "type": "string", "description": "New description for the knowledge base." }, "indexing_technique": { "type": "string", "enum": [ "high_quality", "economy" ] }, "permission": { "type": "string", "enum": [ "only_me", "all_team_members", "partial_members" ] }, "embedding_model_provider": { "type": "string" }, "embedding_model": { "type": "string" }, "retrieval_model": { "$ref": "#/components/schemas/RetrievalModel" }, "partial_member_list": { "type": "array", "description": "List of member IDs for 'partial_members' permission.", "items": { "type": "string" } } } }, "IndexingStatus": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "indexing_status": { "type": "string" }, "processing_started_at": { "type": "number", "format": "float" }, "parsing_completed_at": { "type": "number", "format": "float" }, "cleaning_completed_at": { "type": "number", "format": "float" }, "splitting_completed_at": { "type": "number", "format": "float" }, "completed_at": { "type": "number", "format": "float", "nullable": true }, "paused_at": { "type": "number", "format": "float", "nullable": true }, "error": { "type": "string", "nullable": true }, "stopped_at": { "type": "number", "format": "float", "nullable": true }, "completed_segments": { "type": "integer" }, "total_segments": { "type": "integer" } } }, "DocumentListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" } } }, "DocumentDetail": { "allOf": [ { "$ref": "#/components/schemas/Document" }, { "type": "object", "properties": { "dataset_process_rule": { "$ref": "#/components/schemas/ProcessRule" }, "document_process_rule": { "allOf": [ { "$ref": "#/components/schemas/ProcessRule" }, { "type": "object", "properties": { "id": { "type": "string" }, "dataset_id": { "type": "string" } } } ] }, "indexing_latency": { "type": "number", "format": "float", "nullable": true }, "segment_count": { "type": "integer" }, "average_segment_length": { "type": "integer" }, "doc_language": { "type": "string", "nullable": true } } } ] }, "Segment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "position": { "type": "integer" }, "document_id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "answer": { "type": "string", "nullable": true }, "word_count": { "type": "integer" }, "tokens": { "type": "integer" }, "keywords": { "type": "array", "items": { "type": "string" } }, "index_node_id": { "type": "string" }, "index_node_hash": { "type": "string" }, "hit_count": { "type": "integer" }, "enabled": { "type": "boolean" }, "disabled_at": { "type": "integer", "format": "int64", "nullable": true }, "disabled_by": { "type": "string", "format": "uuid", "nullable": true }, "status": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "integer", "format": "int64" }, "indexing_at": { "type": "integer", "format": "int64" }, "completed_at": { "type": "integer", "format": "int64" }, "error": { "type": "string", "nullable": true }, "stopped_at": { "type": "integer", "format": "int64", "nullable": true } } }, "CreateSegmentsRequest": { "type": "object", "properties": { "segments": { "type": "array", "items": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "description": "The text content of the chunk (or question in Q&A mode)." }, "answer": { "type": "string", "description": "The answer content, required if the document is in Q&A mode." }, "keywords": { "type": "array", "description": "Keywords associated with the chunk.", "items": { "type": "string" } } } } } } }, "SegmentListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } }, "doc_form": { "type": "string" } } }, "SegmentPaginatedResponse": { "allOf": [ { "$ref": "#/components/schemas/SegmentListResponse" }, { "type": "object", "properties": { "has_more": { "type": "boolean" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" } } } ] }, "SegmentDetailResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Segment" }, "doc_form": { "type": "string" } } }, "UpdateSegmentRequest": { "type": "object", "properties": { "segment": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" }, "answer": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "regenerate_child_chunks": { "type": "boolean", "description": "Whether to regenerate child chunks (hierarchical mode)." } } } } }, "RetrieveRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "The search query string." }, "retrieval_model": { "allOf": [ { "$ref": "#/components/schemas/RetrievalModel" }, { "type": "object", "properties": { "metadata_filtering_conditions": { "type": "object", "description": "Conditions for filtering results based on metadata.", "properties": { "logical_operator": { "type": "string", "enum": [ "and", "or" ] }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the metadata field." }, "comparison_operator": { "type": "string", "description": "The operator for comparison." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "nullable": true, "description": "The value to compare against." } } } } } } } } ] } } }, "RetrievedSegment": { "type": "object", "properties": { "segment": { "allOf": [ { "$ref": "#/components/schemas/Segment" }, { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "data_source_type": { "type": "string" }, "name": { "type": "string" } } } } } ] }, "score": { "type": "number", "format": "float" } } }, "RetrieveResponse": { "type": "object", "properties": { "query": { "type": "object", "properties": { "content": { "type": "string" } } }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/RetrievedSegment" } } } }, "Model": { "type": "object", "properties": { "model": { "type": "string" }, "label": { "type": "object", "additionalProperties": { "type": "string" } }, "model_type": { "type": "string" }, "features": { "type": "array", "items": {}, "nullable": true }, "fetch_from": { "type": "string" }, "model_properties": { "type": "object", "properties": { "context_size": { "type": "integer" } } }, "deprecated": { "type": "boolean" }, "status": { "type": "string" }, "load_balancing_enabled": { "type": "boolean" } } }, "ModelProvider": { "type": "object", "properties": { "provider": { "type": "string" }, "label": { "type": "object", "additionalProperties": { "type": "string" } }, "icon_small": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "icon_large": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "status": { "type": "string" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/Model" } } } }, "ChildChunk": { "type": "object", "description": "Represents a child chunk in a hierarchical segmentation.", "properties": { "id": { "type": "string", "format": "uuid" }, "segment_id": { "type": "string", "format": "uuid" }, "content": { "type": "string" }, "word_count": { "type": "integer" }, "tokens": { "type": "integer" }, "index_node_id": { "type": "string" }, "index_node_hash": { "type": "string" }, "status": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "integer", "format": "int64" }, "indexing_at": { "type": "integer", "format": "int64" }, "completed_at": { "type": "integer", "format": "int64" }, "error": { "type": "string", "nullable": true }, "stopped_at": { "type": "integer", "format": "int64", "nullable": true } } }, "CreateChildChunkRequest": { "type": "object", "required": ["content"], "properties": { "content": { "type": "string", "description": "The content of the child chunk." } } }, "UpdateChildChunkRequest": { "type": "object", "required": ["content"], "properties": { "content": { "type": "string", "description": "The updated content for the child chunk." } } }, "ChildChunkResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ChildChunk" } } }, "ChildChunkListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChildChunk" } }, "total": { "type": "integer" }, "total_pages": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "UploadFileResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "size": { "type": "integer" }, "extension": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "Preview URL for the file." }, "download_url": { "type": "string", "format": "uri", "description": "Download URL for the file." }, "mime_type": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "integer", "format": "int64" } } }, "Tag": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "example": "knowledge" }, "binding_count": { "type": "integer" } } } } } }