# Third-Party Dataset Development

> Integrate external document repositories and custom file APIs into FastGPT knowledge bases.

Source: https://doc.fastgpt.io/guide/dataset/third-party/third_dataset
Last Updated: 2026-11-13

> **Online API reference**: See the online API documentation for current Collection creation and sync parameters:
>
> * Mainland China cloud: [System OpenAPI](https://cloud.fastgpt.cn/apidoc/systemopenapi)
> * International cloud: [System OpenAPI](https://cloud.fastgpt.io/apidoc/systemopenapi)
> * Self-hosted: `<instance>/apidoc/systemopenapi`

There are many document libraries available online, such as Lark, Yuque, DingTalk, and others. FastGPT has built-in support for Lark, Yuque, and DingTalk datasets (as well as the generic API Dataset); if you need to integrate other document libraries, follow this guide.

## Unified API Specification

To provide a unified interface for different document libraries, FastGPT defines a standard API specification with 4 endpoints. See the [API File Library endpoints](https://doc.fastgpt.io/guide/dataset/third-party/api_dataset).

All built-in document libraries are extensions of the standard API File Library. Refer to the code in `FastGPT/packages/service/core/dataset/apiDataset/yuqueDataset/api.ts` to build extensions for other document libraries. You need to implement 4 endpoints:

1. Get file list
2. Get file content / file link
3. Get original file preview URL
4. Get file detail information

## Building a Third-Party File Library

The code snippets below use the Yuque Dataset (`YuqueServerSchema`, `yuqueDataset/api.ts`) to show the current Zod schema and adapter contract, while the screenshots illustrate file locations from an earlier Lark Dataset implementation. Match the server schema, form fields, and request adapter to the current source tree.

### 1. Add Third-Party Document Library Parameters

First, go to `FastGPT\packages\global\core\dataset\apiDataset\type.ts` in the FastGPT project and add a Zod schema for the provider configuration and infer its TypeScript type. Include the schema in `ApiDatasetServerSchema`. Design the fields based on your needs. For example, the Yuque Dataset requires `userId` and `token` for authentication.

```ts
export const YuqueServerSchema = z.object({
  userId: z.string(),
  token: z.string().optional(),
  basePath: z.string().optional()
});
export type YuqueServerType = z.infer<typeof YuqueServerSchema>;
```

> If the document library supports a `root directory` selection feature, add a `basePath` field. [See the root directory feature](https://doc.fastgpt.io/guide/dataset/third-party/third_dataset#adding-the-configuration-form)

Add the new server configuration as an optional property on `ApiDatasetServerType`, alongside entries such as `yuqueServer?: YuqueServer`. The Lark example uses `feishuKnowledgeServer?: FeishuKnowledgeServer`.

![Define the server type and add it to ApiDatasetServerType](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-1.png.webp)

### 2. Create the Hook File

Each third-party document library adapter returns four core methods (plus an optional `getFileRawId` helper); follow the current `yuqueDataset/api.ts` contract.

* Create a folder for your document library under `FastGPT\packages\service\core\dataset\apiDataset\`, then create an `api.ts` file inside it
* In `api.ts`, define the following four methods:
  * `listFiles`: Get the file list
  * `getFileContent`: Get file content / file link
  * `getFileDetail`: Get file detail information
  * `getFilePreviewUrl`: Get the original file preview URL

### 3. Add the Dataset Type

In `FastGPT\packages\global\core\dataset\type.ts`, import your new Dataset type.

![3. Add the Dataset Type — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-2.png.webp)

### 4. Add Dataset Data Retrieval

In `packages/global/core/dataset/apiDataset/utils.ts`, extend `filterApiDatasetServerPublicData` to expose safe configuration fields while removing credentials. Use the existing `ApiDatasetResult` success/error contract and error classification helpers; distinguish missing files from authorization, rate-limit, and network failures so sync can handle each correctly.

![4. Add Dataset Data Retrieval — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-3.png.webp)

### 5. Add Dataset Invocation Method

In `packages/service/core/dataset/apiDataset/index.ts`, add a branch in `getApiDatasetRequest` that selects the new adapter from its server configuration. Propagate optional browse-cache settings only where the adapter supports them.

![5. Add Dataset Invocation Method — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-4.png.webp)

## Adding the Frontend

Add your i18n translations in `dataset.json` across `packages/web/i18n/{zh-CN,en,zh-Hant,ko-KR}/`. Add a Dataset name, a configuration-form title, and a description, providing values for each locale.

![Add Dataset name, configuration title, and description translations](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-5.png.webp)

In `FastGPT\packages\service\support\user/audit\util.ts`, add a branch to `getI18nDatasetType` for the new `DatasetTypeEnum` value. Return its translated Dataset name so audit records display the correct label.

![Map Dataset types to translated audit labels](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-6.png.webp)

> Audit-log dataset labels are stored in `packages/web/i18n/{zh-CN,en,zh-Hant,ko-KR}/account_team.json` under the key pattern `dataset.XXX_dataset` (for example, `dataset.feishu_dataset` for Lark Dataset and `dataset.yuque_dataset` for Yuque Dataset).

Add your Dataset icons under `FastGPT\packages\web\components\common\Icon\icons\core\dataset\`. You need two icons: `Outline` (monochrome) and `Color` (colored), as shown below.

![Adding the Frontend — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-7.png.webp)

In `FastGPT\packages\web\components\common\Icon\constants.ts`, register your icons. The `import` path points to where the icons are stored.

![Adding the Frontend — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-8.png.webp)

In `FastGPT\packages\global\core\dataset\constants.ts`, add your Dataset type to both `DatasetTypeEnum` and `ApiDatasetTypeMap`.

|                                                                                                                   |                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| ![Extend DatasetTypeEnum](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-9.png.webp) | ![Configure the Dataset type display mapping](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-10.png.webp) |

> The `courseUrl` field links to the relevant documentation — add it if available.
> Place your integration guide under `FastGPT/document/content/guide/dataset/third-party/` and use its public documentation route for `courseUrl`.
> The `label` value is the Dataset name you added via i18n translations.
> `icon` and `avatar` are the two icons you added earlier.

In `FastGPT\projects\app\src\pages\dataset\list\index.tsx`, add the following. This file handles the menu that appears when clicking the "New" button on the Dataset list page. Add a menu item with its icon, translated label and description, and an `onClick` handler that calls `onSelectDatasetType` with the new `DatasetTypeEnum` value.

![Add the Dataset creation menu item](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-11.png.webp)

In `FastGPT\projects\app\src\pageComponents\dataset\detail\Info\index.tsx`, render a configuration section for the new Dataset type. Show its translated configuration title and account or app identifier. Wire the edit icon to `setEditedAPIDataset`, passing the Dataset ID and its server configuration.

|                                                                                                                                              |                                                                                                                                              |
| -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| ![Render the Dataset configuration and edit action](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-12.png.webp) | ![Configuration section on the Dataset detail page](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-13.png.webp) |

## Adding the Configuration Form

In `FastGPT\projects\app\src\pageComponents\dataset\ApiDatasetForm.tsx`, add the following. This file handles the field input form when creating a Dataset. Import the new server type, add it to the form data type, and render its credential fields when the corresponding Dataset type is selected. Register each required field with validation. The pictured form uses App ID and App Secret; token-based adapters should expose the token fields defined by their server type.

|                                                                                                                                                |                                                                                                                                 |                                                                                                                                                                 |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ![Import the server type into the configuration form](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-14.png.webp) | ![Register required credential inputs](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-15.png.webp) | ![Dataset creation form with credentials and root directory selection](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-16.png.webp) |

For adapters with root directory support, include `renderBaseUrlSelector()` and `renderDirectoryModal()` to display the current path and folder picker. Directory details come from the adapter's `getFileDetail` implementation. The user clicks **Select**, chooses a folder, and clicks **Confirm**; the selected path then appears in the form.

```
{renderBaseUrlSelector()} // Renders the root directory (`basePath`) selector (labeled `Base URL` in the UI)
{renderDirectoryModal()} // The `Select Root Directory` modal that appears when clicking `Select` (see image)
```

|                                                                                                                                               |   |
| --------------------------------------------------------------------------------------------------------------------------------------------- | - |
| ![Adding the Configuration Form — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-17.png.webp) |   |

If the Dataset needs root directory support, also add the following in the `ApiDatasetForm` file.

### 1. Parse the Dataset Type

Watch the form's `apiDatasetServer` value, then read your adapter configuration from it. For this example, use `apiDatasetServer?.feishuKnowledgeServer`.

![Read adapter configuration from form state](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-19.png.webp)

### 2. Add Root Directory Selection Logic and `parentId` Assignment

Include your adapter's `basePath` in the `parentId` calculation. Add a case to `canSelectBaseUrl` that enables folder selection once the required credentials are present, and include those fields in the memoization dependencies. The token-based Lark example checks `feishuKnowledgeServer?.user_access_token`.

![Enable root selection after credential validation](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-20.png.webp)

### 3. Add Field Validation and Assignment Logic

Before loading a path for a new Dataset, validate the required credentials again. Pass `datasetId`, `parentId`, and `apiDatasetServer` to `getApiDatasetPaths`. In `onSelectBaseUrl`, normalize the root selection to an empty string and save the selected value to the adapter's `basePath` field. The example uses `setValue('apiDatasetServer.feishuKnowledgeServer.basePath', value)`.

![Validate path requests and save the selected basePath](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/thirddataset-21.png.webp)

## Tips

After creating the Dataset, verify listing, folder navigation, import, preview, updates, and missing-file handling. Include invalid credentials, 429 responses, and network failures in scoped adapter tests. If you encounter problems that aren't covered in this documentation, it's likely that some configuration was missed. Do a global search for `YuqueServer` and `yuqueServer` to verify that your type has been added everywhere it's needed.
