> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Document Folders

API operations for document folders. Browse the routes below for parameters, request examples, and responses.

API version: Selected per operation

## List document folders

Returns every folder that organizes the knowledge base's documents in one response; `parentID` nests a folder inside another and is null at the top level. Use a folder's `id` as `folderID` to file a document under it.

### Endpoint

```http
GET /v1/stable/document-folder
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Responses

#### 200

Returns every knowledge base folder in the environment, each with its ID, name, parent folder ID, and timestamps.

Schema:

```json
{
  "$ref": "#/components/schemas/StableDocumentFolderListResponse"
}
```

Example:

```json
{
  "folders": [
    {
      "id": "<string>",
      "name": "<string>",
      "parentID": "<string>",
      "createdAt": "<string>",
      "updatedAt": "<string>"
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v1/stable/document-folder?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/document-folder?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v1/stable/document-folder?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document folder list --project-id <projectID> --environment-alias <environmentAlias>
```


## Create document folder

Adds a folder to the knowledge base, at the top level or nested under another folder. Folders only organize documents; retrieval searches every document regardless of its folder.

### Endpoint

```http
POST /v1/stable/document-folder
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableDocumentFolderCreateRequest"
      }
    }
  }
}
```

### Responses

#### 201

Returns the new folder with its generated ID, name, parent folder ID, and timestamps.

Schema:

```json
{
  "$ref": "#/components/schemas/StableDocumentFolderResponse"
}
```

Example:

```json
{
  "folder": {
    "id": "<string>",
    "name": "<string>",
    "parentID": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>"
  }
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/document-folder?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "parentID": null
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/document-folder?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "<string>",
    "parentID": null
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/document-folder?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "name": "<string>",
      "parentID": None
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document folder create --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "name": "<string>",
  "parentID": null
}
JSON
```


## Update document folder

Renames a knowledge base folder, moves it under another folder, or moves it to the top level. A moved folder takes its documents and subfolders with it, and a folder cannot be moved into itself or one of its own subfolders. The response carries only a confirmation message, so refetch the folders to read the new values.

### Endpoint

```http
PATCH /v1/stable/document-folder/{folderID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `folderID`

Required · string

The ID of the knowledge base folder to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/StableDocumentFolderUpdateRequest"
          }
        ]
      }
    }
  }
}
```

### Responses

#### 200

Confirms the folder was updated. The body is a message rather than the revised folder, so refetch the folder list to see its new name or parent.

Schema:

```json
{
  "$ref": "#/components/schemas/StableUpdateResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request PATCH \
  --url 'https://realtime-api.voiceflow.com/v1/stable/document-folder/<folderID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "parentID": "<string>"
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/document-folder/<folderID>?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "<string>",
    "parentID": "<string>"
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.patch(
    'https://realtime-api.voiceflow.com/v1/stable/document-folder/<folderID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "name": "<string>",
      "parentID": "<string>"
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document folder update --folder-id <folderID> --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "name": "<string>",
  "parentID": "<string>"
}
JSON
```


## Delete document folder

Deletes a knowledge base folder together with its subfolders and every document inside them. The response carries only a confirmation message, so refetch the folders and documents to see what is left.

### Endpoint

```http
DELETE /v1/stable/document-folder/{folderID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `folderID`

Required · string

The ID of the knowledge base folder to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Responses

#### 200

Confirms the folder was deleted. The body is a message only, so refetch the folder list to see it gone.

Schema:

```json
{
  "$ref": "#/components/schemas/StableDeleteResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request DELETE \
  --url 'https://realtime-api.voiceflow.com/v1/stable/document-folder/<folderID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/document-folder/<folderID>?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.delete(
    'https://realtime-api.voiceflow.com/v1/stable/document-folder/<folderID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf document folder delete --folder-id <folderID> --project-id <projectID> --environment-alias <environmentAlias>
```


## Schema definitions

### StableDeleteResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the deletion."
    }
  },
  "required": [
    "message"
  ]
}
```

### StableDocumentFolder

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "The name of the folder."
    },
    "parentID": {
      "nullable": true,
      "description": "The ID of the folder this folder is nested in, or null for a top-level folder.",
      "type": "string",
      "minLength": 1
    },
    "createdAt": {
      "type": "string"
    },
    "updatedAt": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "name",
    "parentID",
    "createdAt",
    "updatedAt"
  ]
}
```

### StableDocumentFolderCreateRequest

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "The name of the folder."
    },
    "parentID": {
      "default": null,
      "description": "The ID of the folder to nest this folder in. Omit or pass null for a top-level folder.",
      "nullable": true,
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}
```

### StableDocumentFolderListResponse

```json
{
  "type": "object",
  "properties": {
    "folders": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableDocumentFolder"
      }
    }
  },
  "required": [
    "folders"
  ]
}
```

### StableDocumentFolderResponse

```json
{
  "type": "object",
  "properties": {
    "folder": {
      "$ref": "#/components/schemas/StableDocumentFolder"
    }
  },
  "required": [
    "folder"
  ]
}
```

### StableDocumentFolderUpdateRequest

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "The name of the folder."
    },
    "parentID": {
      "description": "The ID of the folder to move this folder into, or null to move it to the top level. Omit it to keep the folder where it is.",
      "nullable": true,
      "type": "string",
      "minLength": 1
    }
  },
  "additionalProperties": false
}
```

### StableUpdateResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the update."
    }
  },
  "required": [
    "message"
  ]
}
```
