# Create Empty Collection or Folder

> Create an empty virtual collection or folder inside a dataset with optional tags and parent permission inheritance.

Source: https://doc.fastgpt.io/openapi/reference/dataset-collection-create/create
Last Updated: 2026-11-18

## Endpoint Overview

* **Method** : `POST`
* **Path** : `/api/core/dataset/collection/create`
* **Module** : Datasets / Create Collections
* **Authentication** : `Authorization: Bearer <apiKey>`—Personal API Key (access scoped by team member permissions) (see [API Getting Started](https://doc.fastgpt.io/openapi/intro) )
* **Interactive Try-It-Out** : [Open in Scalar API Explorer](https://cloud.fastgpt.io/apidoc/systemopenapi#tag/%E9%9B%86%E5%90%88%E5%88%9B%E5%BB%BA/POST/core/dataset/collection/create) (self-hosted instances: replace the origin with `<instance>/apidoc/systemopenapi#tag/%E9%9B%86%E5%90%88%E5%88%9B%E5%BB%BA/POST/core/dataset/collection/create` )

## Description & Notes

Create an empty virtual dataset collection or folder.

## Request Parameters

### Request Body ( `application/json` )

| Field               | Type                 | Required | Default | Constraints & Description                                                                                                                                                                                                                                                                                                  |
| ------------------- | -------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `datasetId`         | `string`             | Yes      | -       | Dataset ID                                                                                                                                                                                                                                                                                                                 |
| `parentId`          | `string \| null`     | No       | -       | Parent folder ID                                                                                                                                                                                                                                                                                                           |
| `name`              | `string`             | Yes      | -       | Collection name                                                                                                                                                                                                                                                                                                            |
| `type`              | `string` (enum)      | Yes      | -       | Collection type ( `folder` or `virtual` manual collection). Allowed values: `folder` , `virtual`                                                                                                                                                                                                                           |
| `tags`              | `string \| object[]` | No       | -       | List of collection tags. String items map to legacy `default_tag` tags; object items `{ tag, value }` resolve by tag name.                                                                                                                                                                                                 |
| `inheritPermission` | `boolean`            | No       | -       | Whether to inherit parent permissions (default `true` , applies only when `type=folder` ). `true` inherits from parent/dataset; `false` creates an isolated folder with creator `owner` permission only (requires collection-level permissions enabled on the dataset, otherwise returns `collectionPermissionDisabled` ). |

## Request Examples

Replace `YOUR_API_KEY` and placeholder IDs before running. Self-hosted users should replace the base URL with `<instance>/api` .

### cURL Example

```bash
curl --fail-with-body -X POST "https://cloud.fastgpt.io/api/core/dataset/collection/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "datasetId": "string",
  "name": "string",
  "type": "folder"
}'
```

### Minimal Valid JSON Body

```json
{
  "datasetId": "string",
  "name": "string",
  "type": "folder"
}
```

## Response Schema & Examples

Successful `/api/*` calls return the standard FastGPT envelope `{ "code": 200, "statusText": "", "message": "", "data": ... }` , where `data` matches the `200` schema below (when a payload schema is declared; otherwise refer to the status description for runtime `data` semantics).

### HTTP 200

Successfully returned the newly created collection ID

Returns the standard FastGPT success envelope ( `{ "code": 200, "statusText": "", "message": "", "data": ... }` ). The exact `data` payload schema is not declared in this OpenAPI contract; refer to the status description above or inspect runtime responses.
