Folder

Update folder

Update Folder

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

Request

  • Method: PUT
  • Endpoint: {{url}}/v1/folder/:folderId
  • Path Parameter:
  • folderId (string): The unique identifier of the folder you wish to update.

Request Body

name (string) is the only required field. description, assignTo, defaultAssignTo, and source are all optional — omit a field entirely to leave its current value unchanged. This is a partial update: only fields you actually include in the request body are written.

To explicitly clear a value instead of leaving it as-is, send it as an empty string (description) or an empty array (assignTo) — that is different from omitting the field.

  • name (string, required): The new name for the folder.
  • description (string, optional): Short description of the folder's contents. Omit to leave unchanged; send "" to clear.
  • assignTo (string[], optional): User IDs the folder is shared with. Omit (and omit defaultAssignTo) to leave the current sharing list unchanged; send [] to clear it.
  • defaultAssignTo (string, deprecated): Single-user convenience form of assignTo. Prefer assignTo.
  • source (object, optional): Where the folder's content comes from; sending it replaces the stored source.

Example Request Body (rename only — sharing and description are left untouched):

{
 "name": "Folder name 2 Updated"
}

Example Request Body (rename and replace the sharing list):

{
 "name": "Folder name 2 Updated",
 "assignTo": ["64f0a1b2c3d4e5f678901234"]
}

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.

put/folder/{folderId}

Request

  • Base URL: https://api.speakai.co/v1
  • URL: https://api.speakai.co/v1/folder/{folderId}
  • Auth: API key in header x-speakai-key and API key in header x-access-token

Path parameters

folderIdstring required

Request body

folderIdstring

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.

namestring 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.

defaultAssignTostring

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.

assignTostring[]

The user IDs you want the folder assigned to. Sending this replaces the current assignment list. Omitting both assignTo and defaultAssignTo leaves the current assignment list unchanged — send an empty array explicitly if you want to clear it. Optional. No cap on the number of entries. The schema declares a default of an empty array, but that default never reaches the handler.

descriptionstring

A short description of what the folder holds. It is saved exactly as you send it. Omitting this field entirely leaves the existing description unchanged; sending an empty string clears it. 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.

sourceobject

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.

Response

OK

statusstring

Changes

No recorded changes to this operation across all 2 revisions of this API.