FastGPTFastGPT

Integrate knowledge ingestion and retrieval

Use generated API contracts for import, processing checks, retrieval testing, and application association.

📖

Online API Reference: Always refer to the latest online API documentation for complete request/response schemas and endpoint availability:

Prepare a personal API key and the required read/write permissions on the Dataset. See API getting started for authentication setup.

Objects and identifiers

datasetId identifies a knowledge base and collectionId a collection. Content collections hold chunks; folder collections organize other collections. Chunks have retrieval indexes. The interface URL helps locate a resource; submit its identifier in the field specified by the selected operation.

Build an ingestion path

  1. Find knowledge-base creation or existing-base lookup in the generated reference. Verify creation permissions, type, and model configuration.
  2. Choose a collection-creation operation for files, text, URLs, or external sources. Verify its format and processing settings.
  3. Retain returned knowledge-base and collection identifiers. Use the corresponding query operation to inspect processing status and failures.
  4. Once processing completes, submit a question with a known answer to the search-test operation. Inspect returned text and collection origin.
  5. Associate the Dataset with an app and follow business system app integration to verify retrieval through to an answer.

Reuse the material and expected answers from your first knowledge-base Q&A.

Example: import text and retrieve it

First create a general knowledge base with an available embedding model in the interface and copy its ID. Use the origin and key from API getting started, then set FASTGPT_DATASET_ID. This import creates a collection and consumes processing quota; repeating it creates another collection.

export FASTGPT_DATASET_ID='YOUR_DATASET_ID'
curl --fail-with-body "$FASTGPT_ORIGIN/api/core/dataset/collection/create/text" \
  -H "Authorization: Bearer $FASTGPT_API_KEY" \
  -H 'Content-Type: application/json' \
  --data @- <<EOF
{"datasetId":"$FASTGPT_DATASET_ID","name":"Leave policy example","text":"Employees receive 12 days of annual leave."}
EOF

The successful response contains data.collectionId and data.results.insertLen. After import returns, confirm processing has completed in the knowledge-base interface before running retrieval. Results should contain the 12-day annual-leave passage and collection origin. For empty results, check processing state, model permissions, and the knowledge-base ID. Inspect business code and message as well as HTTP status for failures.

curl --fail-with-body "$FASTGPT_ORIGIN/api/core/dataset/searchTest" \
  -H "Authorization: Bearer $FASTGPT_API_KEY" \
  -H 'Content-Type: application/json' \
  --data @- <<EOF
{"datasetId":"$FASTGPT_DATASET_ID","text":"How many days of annual leave do employees receive?","limit":1500}
EOF

Maintenance and failures

Repeated imports, deletions, and replacements change material available to applications. Verify batch operations on a small sample before processing the remainder. Distinguish upload, parsing, segmentation, embedding, and permission failures, retaining collection IDs and errors. Check tag conditions against current filtering and the interface version.

See third-party knowledge sources for synchronization contracts. Historical knowledge-base parameters preserve old fields and examples for migration comparisons.

The 24 endpoints below form the Knowledge Base OpenAPI surface and authenticate via Authorization: Bearer <apiKey>:

1. Knowledge Base Management (dataset)

MethodPathSummaryKey Parameters (Query / Body)
POST/api/core/dataset/createCreate a knowledge base or folderBody: name (required), type (dataset/folder/websiteDataset/externalFile, required), intro (required), vectorModel, agentModel, vlmModel, parentId
POST/api/core/dataset/listList accessible knowledge bases (deprecated; use listV2)Body: parentId, type, searchKey
POST/api/core/dataset/listV2List paginated knowledge bases; pass withFileCount: true to return non-folder file countsBody: parentId, type, searchKey, datasetIds, withFileCount, offset/pageNum, pageSize
GET/api/core/dataset/detailGet knowledge base details (models, permissions, sync status)Query: id (knowledge base ID, required)
DELETE/api/core/dataset/deleteDelete a knowledge base and child resources (owner only)Query: id (knowledge base ID, required)
POST/api/core/dataset/batch/moveBatch-move knowledge bases to a target folderBody: ids (ID array), parentId (target folder ID or empty)
POST/api/core/dataset/batch/deleteBatch-delete multiple knowledge basesBody: ids (ID array)

2. Collection Creation and Ingestion (datasetCollectionCreate)

MethodPathSummaryKey Parameters (Body / Form)
POST/api/core/dataset/collection/createCreate an empty collection or folderBody: datasetId (required), name (required), type (folder/virtual, required), parentId, tags
POST/api/core/dataset/collection/create/localFileUpload a local file to create a collection and start trainingmultipart/form-data: file (binary) + data (JSON string with datasetId, trainingType, chunkSize, tags)
POST/api/core/dataset/collection/create/textCreate a collection from raw text and start trainingBody: datasetId (required), name (required), text (required), trainingType, chunkSettingMode, tags
POST/api/core/dataset/collection/create/linkCrawl a web URL to create a collection and start trainingBody: datasetId (required), link (required), trainingType, metadata (webPageSelector)
POST/api/core/dataset/collection/create/apiCollectionCreate a collection from an external API dataset file (deprecated)Body: datasetId (required), name (required), apiFileId (required), trainingType

3. Collection Query, Update, and Archive Download (datasetCollection)

MethodPathSummaryKey Parameters (Query / Body)
POST/api/core/dataset/collection/listV2List paginated collections (supports search and tagFilters)Body: datasetId (required), parentId, searchText, tagFilters, selectFolder, pageSize (max 100)
GET/api/core/dataset/collection/detailGet collection details (index count, training status, file metadata)Query: id (collection ID, required)
POST/api/core/dataset/collection/updateUpdate collection name, parent folder, enabled state, or tagsBody: id (or datasetId + externalFileId), name, parentId, forbid, tags
POST/api/core/dataset/collection/deleteDelete one or more collections (collection owner only)Query: id or Body: collectionIds (string array)
POST/api/core/dataset/collection/getDownloadTicketRequest a short-lived ticket for batch collection ZIP downloadBody: datasetId (required), collectionIds (required, at least 1 collection ID)
GET/api/core/dataset/collection/batchDownloadStream a ZIP archive of collection source files using a ticketQuery: ticket (required)

4. Data Chunk Maintenance and Search Test (datasetData / datasetOther)

MethodPathSummaryKey Parameters (Query / Body)
POST/api/core/dataset/data/pushDataPush data chunks to the training queue in batch (up to 200 items)Body: collectionId (required), data ({ q, a, indexes }[] array, required), trainingType
POST/api/core/dataset/data/v2/listList paginated data chunks inside a collectionBody: collectionId (required), searchText, offset/pageNum, pageSize
GET/api/core/dataset/data/detailGet a single data chunk and its vector indexesQuery: id (data chunk ID, required)
PUT/api/core/dataset/data/updateUpdate a chunk's q, a, or indexes and re-embedBody: dataId (required), q (required), a, indexes
DELETE/api/core/dataset/data/deleteDelete a single data chunk and its indexesQuery: id (data chunk ID, required)
POST/api/core/dataset/searchTestRun a retrieval test (semantic/full-text/hybrid, image query, rerank)Body: datasetId (required), text, queryImageUrls, limit (max tokens), similarity, searchMode, usingReRank
Earlier section links

Dataset

Create Dataset

Get Dataset List

Get Dataset Details

Delete Dataset

Collection

Common Creation Parameters (Must Read)

Create Empty Collection/Folder

Create a Text Collection

Create a Link Collection

Create a File Collection

Create a Collection from an API Dataset (V1)

Create an External File Collection (Commercial)

Get Collection List

Get Collection Details

Update Collection Info

Delete Collection

Data

Data Structure

Push Data to Processing Queue

Get Collection Data List

Get Single Data Details

Update Single Data

Delete Single Data

Search Test

Edit on GitHub

Last updated