Organize Speak AI media with the folders endpoints

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

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:

{
  "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:

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

Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

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

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:

{
  "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:

{
  "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

Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

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

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

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

Parameters

Get all views for a specific folder

Parameters

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

Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

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

Parameters

Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

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

Parameters

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:

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

Example Response

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

Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

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

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

Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.