---
title: "Organize Speak AI media with the folders endpoints"
description: "Create, list, clone, update, and delete Speak AI folders, and manage the saved views that control how the media inside a folder is filtered."
---

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

# Organize Speak AI media with the folders endpoints


import EndpointIndex from "@/components/api/EndpointIndex.astro";

The Speak AI API exposes 12 folders endpoints under the base URL `https://api.speakai.co/v1`. Every request needs the `x-speakai-key` and `x-access-token` headers described in [Authentication](/api/authentication/).

Manage Folder workflow. Create, Update, Delete folders.

## What can you do with the folders endpoints?

Speak AI groups these 12 endpoints under the folders resource. Each entry below links to the full reference for that endpoint further down this page.

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | [`/folder`](#get-folder) | Get folders |
| `POST` | [`/folder`](#post-folder) | Create folder |
| `GET` | [`/folder/{folderId}`](#get-folder-folder-id) | Get folders info |
| `PUT` | [`/folder/{folderId}`](#put-folder-folder-id) | Update folder |
| `DELETE` | [`/folder/{folderId}`](#delete-folder-folder-id) | Delete folder |
| `GET` | [`/folder/{folderId}/views`](#get-folder-folder-id-views) | Get Views by Folder ID |
| `POST` | [`/folder/{folderId}/views`](#post-folder-folder-id-views) | Create View |
| `PUT` | [`/folder/{folderId}/views/{viewId}`](#put-folder-folder-id-views-view-id) | Update View |
| `DELETE` | [`/folder/{folderId}/views/{viewId}`](#delete-folder-folder-id-views-view-id) | Delete View |
| `POST` | [`/folder/clone`](#post-folder-clone) | Clone Folder |
| `GET` | [`/folder/views`](#get-folder-views) | Get All Views |
| `POST` | [`/folder/views/clone`](#post-folder-views-clone) | Clone View |

<h2 id="get-folder">Get folders</h2>

#### Get Folders

This endpoint retrieves a list of folders based on pagination and sorting criteria.

##### Request Parameters

- **page** (integer, required): The page number to retrieve. This parameter is used for pagination.

- **pageSize** (integer, required): The number of folders to return per page. This parameter controls the size of the result set.

- **sortBy** (string, required): The field by which to sort the folders. In this case, it is sorted by `createdAt`.

##### Response Format

The response will contain the following structure:

- **status** (string): The status of the request.

- **data** (object): Contains the details of the folders retrieved.

- **totalCount** (integer): The total number of folders available.

- **pages** (integer or null): The total number of pages available based on the pagination.

- **folders** (array): An array of folder objects, each containing:

- **_id** (string): The unique identifier for the folder.

- **defaultAssignTo** (string): The default user assigned to the folder.

- **showOrder** (integer): The order in which the folder should be displayed.

- **name** (string): The name of the folder.

- **folderId** (string): The identifier for the folder.

- **createdAt** (string): The creation date of the folder.

- **updatedAt** (string): The last updated date of the folder.

- **user** (object): An object representing the user associated with the folder.

- **_id** (string): The unique identifier for the user.

- **firstName** (string): The first name of the user.

- **lastName** (string): The last name of the user.

- **userId** (string): The identifier for the user associated with the folder.

##### Notes

- Ensure that the `page` and `pageSize` parameters are set correctly to retrieve the desired set of folders.

- The response may return an empty array if no folders are available for the specified page and size.

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | No |  |
| `pageSize` | query | integer | No |  |
| `sortBy` | query | string | No |  |
| `from` | query | string | No | You can pass in the dateFormat |
| `to` | query | string | No | You can pass in the dateFormat |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X GET 'https://api.speakai.co/v1/folder?page=0&pageSize=5&sortBy=createdAt' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="get-folder" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.totalCount` | integer |
| `data.pages` | string |
| `data.folders` | object[] |

Deeper nested fields are not listed. See the example response below for the full shape.

Example response (Get folders), `application/json`.

```json
{
  "status": "success",
  "data": {
"totalCount": 93,
"pages": null,
"folders": [
  {
    "_id": "61e3d27bxxxx5041a7",
    "defaultAssignTo": "",
    "showOrder": 1,
    "name": "AudioAudioAudioAudioAudioAudioAudioAudioAu",
    "folderId": "905c208f1c07",
    "createdAt": "2022-01-16T08:08:27.821Z",
    "updatedAt": "2025-01-06T15:05:38.939Z",
    "user": {
      "_id": "5d03a9d5xxxx8cf89",
      "firstName": "Vatsal",
      "lastName": "Shah"
    },
    "userId": "5d03a9d5dxxxxc8cf89"
  }
]
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="post-folder">Create folder</h2>

#### Create a New Folder

This endpoint allows you to create a new folder by sending an HTTP POST request to the specified URL.

##### Request Body

- **name** (string, required): The name of the folder to be created.

Example:

``` json
{
 "name": "Folder name 2"
}

```

##### Response

- **status** (string): The status of the request.

- **data**

- **folderId** (string): The ID of the newly created folder.

- **message** (string): A message related to the folder creation.

Example:

``` json
{
 "status": "",
 "data": {
 "folderId": "",
 "message": ""
 }
}

```

### Request body

Fields marked **required** are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

| Field | Type | Description |
| --- | --- | --- |
| `folderId` | string | An existing folder ID. The create handler ignores this value, so you can leave it out. Optional. Empty string and null are accepted. |
| `name` | string, **required** | The name you want to give the folder. Leading and trailing whitespace is stripped before the folder is saved. Required. The schema declares.trim, but the validation middleware discards the schema's converted value, so the trimming you see comes from the handler itself (it calls name.trim for both the duplicate check and the saved value) and from the Folder model, which sets trim: true on name. No maximum length is enforced anywhere. |
| `defaultAssignTo` | string | A single user ID to assign the folder to. Use assignTo instead. When you send this and omit assignTo, the server wraps the value into a one-item assignTo array. Optional. Empty string and null are accepted. The schema declares a default of an empty string, but that default never reaches the handler because the middleware throws away the schema's converted value. |
| `assignTo` | string[] | The user IDs you want the folder assigned to. Optional. No cap on the number of entries. The schema declares a default of an empty array, but that default never reaches the handler. Omitting assignTo is exactly what lets defaultAssignTo take effect, because the handler checks Array.isArray(assignTo) first. |
| `description` | string | A short description of what the folder holds. It is saved exactly as you send it. Optional. Empty string and null are accepted. The schema declares.trim and a default of an empty string, but neither takes effect: the middleware discards the schema's converted value and the Folder model does not trim description, so leading and trailing whitespace is preserved. |
| `source` | object | Where the folder's content comes from. The create handler ignores this value, so it only takes effect on PUT /folder/\{folderId\}. Optional, and null is accepted. Accepts three optional inner keys: type (string, empty string and null allowed), subCategory (string, empty string and null allowed), and fields (array, null allowed, with no item schema declared so any entries pass). Any other inner key is rejected, including goal, which the Folder model stores but this schema does not accept. |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X POST 'https://api.speakai.co/v1/folder' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Folder name 2"
}'
```

</CodePanel>

<ResponsePanel id="post-folder" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.folderId` | string |
| `data.message` | string |

Example response (Create folder), `application/json`.

```json
{
  "status": "success",
  "data": {
"folderId": "0648e533f72c",
"message": "Folder name 2 folder created successfully"
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="get-folder-folder-id">Get folders info</h2>

#### Get Folder Details

This endpoint retrieves the details of a specific folder identified by its unique `folderId`.

##### Request Parameters

- `folderId` (path parameter): The unique identifier of the folder you want to retrieve. This should be a valid ID corresponding to an existing folder in the system.

##### Response

The response will contain a JSON object with the following structure:

- `status`: A string indicating the status of the request.

- `data`: An object containing detailed information about the folder:

 - `_id`: The unique identifier of the folder.

 - `companyId`: The ID of the company associated with the folder.

 - `userId`: The ID of the user who owns the folder.

 - `folderType`: The type of folder.

 - `name`: The name of the folder.

 - `description`: A brief description of the folder.

 - `defaultAssignTo`: The default user assigned to the folder (can be null).

 - `showOrder`: An integer indicating the order in which the folder is displayed.

 - `userShowOrder`: An object mapping user IDs to their specific display order for the folder.

 - `isDeleted`: A boolean indicating whether the folder has been deleted.

 - `folderId`: The ID of the folder.

 - `createdAt`: The timestamp when the folder was created.

 - `updatedAt`: The timestamp when the folder was last updated.

 - `__v`: The version key for the document.

 - `source`: An object containing:

 - `type`: The type of source associated with the folder.

 - `subCategory`: The subcategory of the source.

 - `shared`: An array containing information about users or entities with whom the folder is shared.

##### Notes

- Ensure that the `folderId` provided in the request is valid, as an invalid ID will result in an error response.

- The `isDeleted` field in the response indicates whether the folder is currently active or has been marked for deletion.

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `folderId` | path | string | Yes |  |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X GET 'https://api.speakai.co/v1/folder/e88575b384b6' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="get-folder-folder-id" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data._id` | string |
| `data.companyId` | string |
| `data.userId` | string |
| `data.folderType` | string |
| `data.name` | string |
| `data.description` | string |
| `data.defaultAssignTo` | string |
| `data.showOrder` | integer |
| `data.userShowOrder` | object |
| `data.isDeleted` | boolean |
| `data.folderId` | string |
| `data.createdAt` | string (date-time) |
| `data.updatedAt` | string (date-time) |
| `data.__v` | integer |
| `data.source` | object |
| `data.shared` | any[] |

Deeper nested fields are not listed. See the example response below for the full shape.

Example response (Get folders info), `application/json`.

```json
{
  "status": "success",
  "data": {
"_id": "6776f1459df32xxx30f8",
"companyId": "5e21c8ddxxxxxx2c64214816",
"userId": "5d03a9d5d4xxxxxc8cf89",
"folderType": "sub",
"name": "v35",
"description": "",
"defaultAssignTo": null,
"showOrder": 2,
"userShowOrder": {
  "5d03a9d5d4bca272e9c8cf89": 2
},
"isDeleted": false,
"folderId": "e8857xxx4b6",
"createdAt": "2025-01-02T20:04:21.511Z",
"updatedAt": "2025-01-06T15:05:38.939Z",
"__v": 0,
"source": {
  "type": "content",
  "subCategory": "podcast"
},
"shared": []
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="put-folder-folder-id">Update folder</h2>

#### Update Folder

This endpoint allows you to update the details of a specific folder identified by its `folderId`.

##### Request

- **Method**: `PUT`
- **Endpoint**: `https://api.speakai.co/v1/folder/{folderId}`
- **Path Parameter**:
 - `folderId` (string): The unique identifier of the folder you wish to update.

##### Request Body

The request body should be in JSON format and must include the following parameter:

- `name` (string): The new name for the folder.

**Example Request Body**:
```json
{
 "name": "Folder name 2 Updated"
}
```

##### Response

Upon a successful update, the response will be in JSON format and will include the following fields:

- `status` (string): The status of the request.
- `data` (object): Contains additional information about the update.
 - `folderId` (string): The ID of the updated folder.
 - `message` (string): A message indicating the result of the update.
 - `fields` (array): An array that may contain any relevant fields related to the update.

**Example Response**:
```json
{
 "status": "",
 "data": {
 "folderId": "",
 "message": "",
 "fields": []
 }
}
```

##### Notes

Ensure that the `folderId` in the URL is valid and that you have the necessary permissions to update the folder.

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `folderId` | path | string | Yes |  |

### Request body

Fields marked **required** are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

| Field | Type | Description |
| --- | --- | --- |
| `folderId` | string | An existing folder ID. The update handler takes the folder from the path instead, so this body value is ignored. Optional. Empty string and null are accepted. |
| `name` | string, **required** | The new name for the folder. Leading and trailing whitespace is stripped before it is saved. Required. The schema declares.trim, but the middleware discards the schema's converted value, so the trimming comes from the Folder model, which sets trim: true on name. No maximum length is enforced. |
| `defaultAssignTo` | string | A single user ID to assign the folder to. Use assignTo instead. When you send this and omit assignTo, the server wraps the value into a one-item assignTo array. Optional. Empty string and null are accepted. The schema declares a default of an empty string, but that default never reaches the handler. |
| `assignTo` | string[] | The user IDs you want the folder assigned to. Sending this replaces the current assignment list. Omitting both assignTo and defaultAssignTo clears the list. Optional. No cap on the number of entries. The schema declares a default of an empty array, but that default never reaches the handler; the handler falls back to an empty array on its own. |
| `description` | string | A short description of what the folder holds. It is saved exactly as you send it, and omitting it clears the existing description. Optional. Empty string and null are accepted. The schema declares.trim and a default of an empty string, but neither takes effect, so leading and trailing whitespace is preserved. |
| `source` | object | Where the folder's content comes from. Sending it replaces the folder's stored source, and sending source.fields with entries also creates the matching folder fields and a new default view for the folder. Optional, and null is accepted. Accepts three optional inner keys: type (string, empty string and null allowed), subCategory (string, empty string and null allowed), and fields (array, null allowed, with no item schema declared so any entries pass). Only type and subCategory are persisted on the folder document; the Folder model's source sub-schema has no fields path, so fields is consumed to create folder fields rather than stored. |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X PUT 'https://api.speakai.co/v1/folder/0648e533f72c' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Folder name 2 Updated"
}'
```

</CodePanel>

<ResponsePanel id="put-folder-folder-id" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.folderId` | string |
| `data.message` | string |
| `data.fields` | any[] |

Example response (Update folder), `application/json`.

```json
{
  "status": "success",
  "data": {
"folderId": "0648e533f72c",
"message": "Folder name 2 Updated folder updated successfully",
"fields": []
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="delete-folder-folder-id">Delete folder</h2>

#### DELETE /v1/folder/\{folderId\}

This endpoint is used to delete a specific folder identified by the `folderId`. The deletion operation will remove the folder and all its contents from the system.

##### Request Parameters

- `folderId` (path parameter): The unique identifier of the folder that you wish to delete. This parameter is required.

##### Response Structure

Upon successful deletion, the response will return a JSON object with the following structure:

- `status`: A string indicating the status of the operation (e.g., success or failure).

- `message`: A string providing additional information about the result of the deletion operation.

##### Example Response

``` json
{
 "status": "success",
 "message": "Folder deleted successfully."
}

```

In case of an error, the response may contain an appropriate error message indicating what went wrong.

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `folderId` | path | string | Yes |  |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X DELETE 'https://api.speakai.co/v1/folder/0648e533f72c' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="delete-folder-folder-id" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `message` | string |

Example response (Delete folder), `application/json`.

```json
{
  "status": "success",
  "message": "Folder successfully deleted."
}
```

</div>

</ResponsePanel>

</div>

<h2 id="get-folder-folder-id-views">Get Views by Folder ID</h2>

Get all views for a specific folder

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `folderId` | path | string | Yes | The ID of the folder to get views for |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X GET 'https://api.speakai.co/v1/folder/your_folder_id_here/views' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="get-folder-folder-id-views" statuses={[{"code":"200","description":"Success. This spec records no example response body for this endpoint."}]}>

<div slot="status-200">

**`200` Success. This spec records no example response body for this endpoint.**

The spec records no example response body for this status code.

</div>

</ResponsePanel>

</div>

<h2 id="post-folder-folder-id-views">Create View</h2>

Create a new view for a specific folder. Column types can be:

**FieldType values:**
- text
- url
- boolean
- date
- datetime
- number
- currency

**DefaultViewColumn values:**
- name
- duration
- tags
- sentiment
- datetime
- createdAt
- updatedAt

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `folderId` | path | string | Yes | The ID of the folder to create view for |

### Request body

Fields marked **required** are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

| Field | Type | Description |
| --- | --- | --- |
| `name` | string, **required** | The name for the new view. Required. |
| `isDefault` | boolean | Whether this view becomes the folder's default view. Setting it to true clears the default flag on your other active views in the folder. Optional. The schema declares a default of false, but the middleware discards the schema's converted value, so an omitted isDefault reaches the handler as undefined. The stored value still ends up false, because the FolderView model defaults isDefault to false. |
| `columns` | object[], **required** | The columns the view shows, in the order you want them displayed. Required. Each entry must be an object matching columnSchema. No cap on the number of entries. An empty array passes validation, because the array has no.min. |
| `columns[].fieldId` | string | The ID of the custom field this column shows. Leave it empty for a built-in column. Optional. Empty string and null are accepted. |
| `columns[].name` | string | The heading shown for this column. Required. |
| `columns[].type` | string | What kind of value the column holds. The accepted set is the FieldType values followed by the DefaultViewColumn values. Required. The value must be one of the listed values. The set is built from Object.values(FieldType) and Object.values(DefaultViewColumn), both declared in speak-shared and re-exported through and The raw.valid list contains "datetime" twice, because it appears in both enums; the accepted set is the 15 distinct values listed here. One of: `text`, `url`, `boolean`, `date`, `datetime`, `number`, `currency`, `name`, `duration`, `tags`, `sentiment`, `size`, `mediaType`, `createdAt`, `updatedAt`. |
| `columns[].definition` | string | An optional label describing what the column is derived from. Optional. Empty string and null are accepted. |
| `columns[].order` | number | The position of the column in the view, counting from zero. The server replaces a value of 0 with the column's position in the array you sent, so a column with order 0 in third position is stored as 2. Required. Declared as Any number passes; there is no minimum and no integer-only rule. The handler stores col.order \|\| index, which is why 0 is overwritten. |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X POST 'https://api.speakai.co/v1/folder/your_folder_id_here/views' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "My Custom View",
  "isDefault": false,
  "columns": [
{
  "fieldId": "",
  "name": "Name",
  "type": "name",
  "definition": "",
  "order": 0
},
{
  "fieldId": "",
  "name": "Duration",
  "type": "duration",
  "definition": "duration",
  "order": 1
},
{
  "fieldId": "",
  "name": "Tags",
  "type": "tags",
  "definition": "tags",
  "order": 2
},
{
  "fieldId": "",
  "name": "Sentiment",
  "type": "sentiment",
  "definition": "sentiment",
  "order": 3
},
{
  "fieldId": "",
  "name": "Created At",
  "type": "datetime",
  "definition": "createdAt",
  "order": 4
}
  ]
}'
```

</CodePanel>

<ResponsePanel id="post-folder-folder-id-views" statuses={[{"code":"200","description":"Success. This spec records no example response body for this endpoint."}]}>

<div slot="status-200">

**`200` Success. This spec records no example response body for this endpoint.**

The spec records no example response body for this status code.

</div>

</ResponsePanel>

</div>

<h2 id="put-folder-folder-id-views-view-id">Update View</h2>

Update an existing view. Note: isDefault is required in update operation.

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `folderId` | path | string | Yes | The ID of the folder |
| `viewId` | path | string | Yes | The ID of the view to update |

### Request body

Fields marked **required** are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

| Field | Type | Description |
| --- | --- | --- |
| `name` | string, **required** | The new name for the view. Required. |
| `isDefault` | boolean, **required** | Whether this view is the folder's default view. Unlike the create call, you must send this value on every update. Setting it to true clears the default flag on your other active views in the folder. Required, with no default declared, so omitting it returns 400. |
| `columns` | object[], **required** | The full set of columns the view shows, in display order. This replaces the view's existing columns. Required. Each entry must be an object matching columnSchema. No cap on the number of entries. An empty array passes validation, because the array has no.min. |
| `columns[].fieldId` | string | The ID of the custom field this column shows. Leave it empty for a built-in column. Optional. Empty string and null are accepted. |
| `columns[].name` | string | The heading shown for this column. Required. |
| `columns[].type` | string | What kind of value the column holds. The accepted set is the FieldType values followed by the DefaultViewColumn values. Required. The value must be one of the listed values. The set is built from Object.values(FieldType) and Object.values(DefaultViewColumn), both declared in speak-shared and re-exported through and The raw.valid list contains "datetime" twice, because it appears in both enums; the accepted set is the 15 distinct values listed here. One of: `text`, `url`, `boolean`, `date`, `datetime`, `number`, `currency`, `name`, `duration`, `tags`, `sentiment`, `size`, `mediaType`, `createdAt`, `updatedAt`. |
| `columns[].definition` | string | An optional label describing what the column is derived from. Optional. Empty string and null are accepted. |
| `columns[].order` | number | The position of the column in the view, counting from zero. The server replaces a value of 0 with the column's position in the array you sent, so a column with order 0 in third position is stored as 2. Required. Declared as Any number passes; there is no minimum and no integer-only rule. The handler stores col.order \|\| index, which is why 0 is overwritten. |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X PUT 'https://api.speakai.co/v1/folder/your_folder_id_here/views/your_view_id_here' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Updated View Name",
  "isDefault": true,
  "columns": [
{
  "fieldId": "",
  "name": "Name",
  "type": "name",
  "definition": "",
  "order": 0
},
{
  "fieldId": "",
  "name": "Duration",
  "type": "duration",
  "definition": "duration",
  "order": 1
},
{
  "fieldId": "",
  "name": "Tags",
  "type": "tags",
  "definition": "tags",
  "order": 2
},
{
  "fieldId": "",
  "name": "Sentiment",
  "type": "sentiment",
  "definition": "sentiment",
  "order": 3
},
{
  "fieldId": "",
  "name": "Created At",
  "type": "datetime",
  "definition": "createdAt",
  "order": 4
}
  ]
}'
```

</CodePanel>

<ResponsePanel id="put-folder-folder-id-views-view-id" statuses={[{"code":"200","description":"Success. This spec records no example response body for this endpoint."}]}>

<div slot="status-200">

**`200` Success. This spec records no example response body for this endpoint.**

The spec records no example response body for this status code.

</div>

</ResponsePanel>

</div>

<h2 id="delete-folder-folder-id-views-view-id">Delete View</h2>

Delete a view (soft delete - sets isActive to false)

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `folderId` | path | string | Yes | The ID of the folder |
| `viewId` | path | string | Yes | The ID of the view to delete |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X DELETE 'https://api.speakai.co/v1/folder/your_folder_id_here/views/your_view_id_here' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="delete-folder-folder-id-views-view-id" statuses={[{"code":"200","description":"Success. This spec records no example response body for this endpoint."}]}>

<div slot="status-200">

**`200` Success. This spec records no example response body for this endpoint.**

The spec records no example response body for this status code.

</div>

</ResponsePanel>

</div>

<h2 id="post-folder-clone">Clone Folder</h2>

#### Clone Folder

This endpoint allows the user to clone a folder by making an HTTP POST request to the specified URL.

##### Request Body

- `folderId` (string) - The ID of the folder to be cloned.

- `name` (string) - The name of the new folder.

- `description` (string) - The description of the new folder.

- `defaultAssignTo` (string) - The default assignee for the new folder.

- `isSaveDefaultView` (boolean) - Indicates whether the default view should be saved.

##### Response

The response of this request is a JSON object with the following schema:

``` json
{
 "type": "object",
 "properties": {
 "status": {
 "type": "string"
 },
 "data": {
 "type": "object",
 "properties": {
 "folderId": {
 "type": "string"
 },
 "message": {
 "type": "string"
 }
 }
 }
 }
}

```

##### Example Response

``` json
{
 "status": "",
 "data": {
 "folderId": "",
 "message": ""
 }
}

```

### Request body

Fields marked **required** are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

| Field | Type | Description |
| --- | --- | --- |
| `folderId` | string, **required** | The ID of the folder you want to copy. Required. Empty string and null are not accepted. |
| `name` | string | The name for the new copy. Leave it out and the server names the copy "\<original folder name> (Clone)". Optional. Empty string and null are accepted. An empty string is treated as absent by the handler, because it falls back on a falsy check. |
| `description` | string | A description for the new copy. Leave it out and the original folder's description is carried over, falling back to an empty string. Optional. Empty string and null are accepted. An empty string is treated as absent by the handler, because it falls back on a falsy check. |
| `defaultAssignTo` | string | A single user ID to assign the copy to. Use assignTo instead. When you send this and omit assignTo, the server wraps the value into a one-item assignTo array. Optional. Empty string and null are accepted. No default is declared. |
| `assignTo` | string[] | The user IDs you want the new copy assigned to. The copy does not inherit the original folder's assignment list, so send this if you want the assignment carried over. Optional. No cap on the number of entries. The schema declares a default of an empty array, but that default never reaches the handler; omitting assignTo is what lets defaultAssignTo take effect. |
| `isSaveDefaultView` | boolean | Whether to copy the source folder's default view onto the new folder. Send true explicitly if you want the view copied. Optional. The schema declares a default of true, but the middleware discards the schema's converted value, so an omitted isSaveDefaultView reaches the handler as undefined and the default view is not copied. There is no model-level default to fall back on here, because the flag only gates a branch in the handler. |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X POST 'https://api.speakai.co/v1/folder/clone' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "folderId": "905c208f1c07",
  "name": "New Folder Name",
  "description": "New Folder description",
  "defaultAssignTo": "",
  "isSaveDefaultView": true
}'
```

</CodePanel>

<ResponsePanel id="post-folder-clone" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.folderId` | string |
| `data.message` | string |

Example response (Create folder), `application/json`.

```json
{
  "status": "success",
  "data": {
"folderId": "0648e533f72c",
"message": "Folder name 2 folder created successfully"
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="get-folder-views">Get All Views</h2>

Get all views across all folders for the company. Used to populate dropdown for cloning views.

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X GET 'https://api.speakai.co/v1/folder/views' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="get-folder-views" statuses={[{"code":"200","description":"Success. This spec records no example response body for this endpoint."}]}>

<div slot="status-200">

**`200` Success. This spec records no example response body for this endpoint.**

The spec records no example response body for this status code.

</div>

</ResponsePanel>

</div>

<h2 id="post-folder-views-clone">Clone View</h2>

Clone a view from source folder to target folder. Use 'Get All Views' to get available view IDs for cloning.

**Request rules.** `targetFolderId` must differ from `sourceFolderId`. Sending the same id for both is rejected.

### Request body

Fields marked **required** are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

| Field | Type | Description |
| --- | --- | --- |
| `sourceFolderId` | string, **required** | The ID of the folder that holds the view you want to copy. Required. |
| `targetFolderId` | string, **required** | The ID of the folder you want the copied view added to. It must be a different folder from sourceFolderId. Required. Rejected when it equals sourceFolderId,. invalid(the schema). The error message is "Source and target folder IDs cannot be the same". |
| `viewId` | string, **required** | The ID of the view inside the source folder that you want to copy. It must belong to an active view, otherwise the request returns 404. Required. |
| `name` | string, **required** | The name for the copied view in the target folder. Required. |
| `isDefault` | boolean | Whether the copied view becomes the default view for the target folder. Setting it to true clears the default flag on your other active views in that folder. Optional. The schema declares a default of false, but the middleware discards the schema's converted value, so an omitted isDefault reaches the handler as undefined. The stored value still ends up false, because the FolderView model defaults isDefault to false. |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X POST 'https://api.speakai.co/v1/folder/views/clone' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "sourceFolderId": "source_folder_id_here",
  "targetFolderId": "target_folder_id_here",
  "viewId": "view_id_to_clone_here",
  "name": "Cloned View Name",
  "isDefault": false
}'
```

</CodePanel>

<ResponsePanel id="post-folder-views-clone" statuses={[{"code":"200","description":"Success. This spec records no example response body for this endpoint."}]}>

<div slot="status-200">

**`200` Success. This spec records no example response body for this endpoint.**

The spec records no example response body for this status code.

</div>

</ResponsePanel>

</div>

## Related pages

- [API reference](/api/) for the base URL, authentication, and the error format.
- [Authenticate with the Speak AI API using access tokens](/api/authentication/)
- [Upload audio and video to Speak AI and read insights](/api/media/)
- [Create and update live transcription sessions in Speak AI](/api/live-transcription/)
- [Analyze text notes with the Speak AI text endpoints](/api/text/)

Get an API key on the [Speak AI developer page](https://app.speakai.co/developers?utm_source=docs&utm_medium=referral&utm_campaign=api-reference&utm_content=api-folders).

Source: https://docs.speakai.co/api/folders/index.mdx